Documentation comments for public interface

kaustubh-seachange · Sep 15, 2015 · acc0eb4 · acc0eb4
1 parent 0b572b3
commit acc0eb4
Show file tree

Hide file tree

Showing 13 changed files with 205 additions and 46 deletions.
diff --git a/BluetoothKit.xcodeproj/project.pbxproj b/BluetoothKit.xcodeproj/project.pbxproj
@@ -7,9 +7,9 @@
 	objects = {
 
 /* Begin PBXBuildFile section */
-		C66888AD1B978181003C8DBB /* BKDiscovery.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888AC1B978181003C8DBB /* BKDiscovery.swift */; settings = {ASSET_TAGS = (); }; };
-		C66888AF1B984792003C8DBB /* BKConfiguration.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888AE1B984792003C8DBB /* BKConfiguration.swift */; settings = {ASSET_TAGS = (); }; };
-		C66888B11B984AB7003C8DBB /* BKPeripheralConfiguration.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888B01B984AB7003C8DBB /* BKPeripheralConfiguration.swift */; settings = {ASSET_TAGS = (); }; };
+		C66888AD1B978181003C8DBB /* BKDiscovery.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888AC1B978181003C8DBB /* BKDiscovery.swift */; };
+		C66888AF1B984792003C8DBB /* BKConfiguration.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888AE1B984792003C8DBB /* BKConfiguration.swift */; };
+		C66888B11B984AB7003C8DBB /* BKPeripheralConfiguration.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888B01B984AB7003C8DBB /* BKPeripheralConfiguration.swift */; };
 		C67A22361B8C49CC00CB74CE /* BKConnectionAttempt.swift in Sources */ = {isa = PBXBuildFile; fileRef = C67A22351B8C49CC00CB74CE /* BKConnectionAttempt.swift */; };
 		C67A22711B8C7EF300CB74CE /* BKPeripheral.swift in Sources */ = {isa = PBXBuildFile; fileRef = C67A22701B8C7EF300CB74CE /* BKPeripheral.swift */; };
 		C67A22731B8C80C300CB74CE /* BKAvailability.swift in Sources */ = {isa = PBXBuildFile; fileRef = C67A22721B8C80C300CB74CE /* BKAvailability.swift */; };
@@ -163,6 +163,8 @@
 		C687E38F1B8B496400B702D8 /* Project object */ = {
 			isa = PBXProject;
 			attributes = {
+				LastSwiftMigration = 0710;
+				LastSwiftUpdateCheck = 0710;
 				LastUpgradeCheck = 0700;
 				ORGANIZATIONNAME = "Rasmus Taulborg Hummelmose";
 				TargetAttributes = {

diff --git a/Example/BKExample.xcodeproj/project.pbxproj b/Example/BKExample.xcodeproj/project.pbxproj
@@ -7,17 +7,17 @@
 	objects = {
 
 /* Begin PBXBuildFile section */
-		C668889C1B970123003C8DBB /* NSData+NumberOfBytes.swift in Sources */ = {isa = PBXBuildFile; fileRef = C668888D1B970123003C8DBB /* NSData+NumberOfBytes.swift */; settings = {ASSET_TAGS = (); }; };
-		C668889D1B970123003C8DBB /* UIImage+Color.swift in Sources */ = {isa = PBXBuildFile; fileRef = C668888E1B970123003C8DBB /* UIImage+Color.swift */; settings = {ASSET_TAGS = (); }; };
-		C668889E1B970123003C8DBB /* AppDelegate.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888901B970123003C8DBB /* AppDelegate.swift */; settings = {ASSET_TAGS = (); }; };
-		C668889F1B970123003C8DBB /* Colors.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888911B970123003C8DBB /* Colors.swift */; settings = {ASSET_TAGS = (); }; };
-		C66888A01B970123003C8DBB /* Logger.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888921B970123003C8DBB /* Logger.swift */; settings = {ASSET_TAGS = (); }; };
-		C66888A11B970123003C8DBB /* AvailabilityViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888941B970123003C8DBB /* AvailabilityViewController.swift */; settings = {ASSET_TAGS = (); }; };
-		C66888A21B970123003C8DBB /* CentralViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888961B970123003C8DBB /* CentralViewController.swift */; settings = {ASSET_TAGS = (); }; };
-		C66888A31B970123003C8DBB /* PeripheralViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888971B970123003C8DBB /* PeripheralViewController.swift */; settings = {ASSET_TAGS = (); }; };
-		C66888A41B970123003C8DBB /* RemotePeripheralViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888981B970123003C8DBB /* RemotePeripheralViewController.swift */; settings = {ASSET_TAGS = (); }; };
-		C66888A51B970123003C8DBB /* RoleSelectionViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888991B970123003C8DBB /* RoleSelectionViewController.swift */; settings = {ASSET_TAGS = (); }; };
-		C66888A61B970123003C8DBB /* AvailabilityView.swift in Sources */ = {isa = PBXBuildFile; fileRef = C668889B1B970123003C8DBB /* AvailabilityView.swift */; settings = {ASSET_TAGS = (); }; };
+		C668889C1B970123003C8DBB /* NSData+NumberOfBytes.swift in Sources */ = {isa = PBXBuildFile; fileRef = C668888D1B970123003C8DBB /* NSData+NumberOfBytes.swift */; };
+		C668889D1B970123003C8DBB /* UIImage+Color.swift in Sources */ = {isa = PBXBuildFile; fileRef = C668888E1B970123003C8DBB /* UIImage+Color.swift */; };
+		C668889E1B970123003C8DBB /* AppDelegate.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888901B970123003C8DBB /* AppDelegate.swift */; };
+		C668889F1B970123003C8DBB /* Colors.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888911B970123003C8DBB /* Colors.swift */; };
+		C66888A01B970123003C8DBB /* Logger.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888921B970123003C8DBB /* Logger.swift */; };
+		C66888A11B970123003C8DBB /* AvailabilityViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888941B970123003C8DBB /* AvailabilityViewController.swift */; };
+		C66888A21B970123003C8DBB /* CentralViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888961B970123003C8DBB /* CentralViewController.swift */; };
+		C66888A31B970123003C8DBB /* PeripheralViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888971B970123003C8DBB /* PeripheralViewController.swift */; };
+		C66888A41B970123003C8DBB /* RemotePeripheralViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888981B970123003C8DBB /* RemotePeripheralViewController.swift */; };
+		C66888A51B970123003C8DBB /* RoleSelectionViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = C66888991B970123003C8DBB /* RoleSelectionViewController.swift */; };
+		C66888A61B970123003C8DBB /* AvailabilityView.swift in Sources */ = {isa = PBXBuildFile; fileRef = C668889B1B970123003C8DBB /* AvailabilityView.swift */; };
 		C67653F51B8E2D3C00D43F8E /* BluetoothKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = C67653F41B8E2D2B00D43F8E /* BluetoothKit.framework */; };
 		C67653F61B8E2D3C00D43F8E /* BluetoothKit.framework in Embed Frameworks */ = {isa = PBXBuildFile; fileRef = C67653F41B8E2D2B00D43F8E /* BluetoothKit.framework */; settings = {ATTRIBUTES = (CodeSignOnCopy, RemoveHeadersOnCopy, ); }; };
 		C67654401B8F051C00D43F8E /* SnapKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = C67654391B8F050600D43F8E /* SnapKit.framework */; };
@@ -306,6 +306,8 @@
 		C67A22381B8C7D1B00CB74CE /* Project object */ = {
 			isa = PBXProject;
 			attributes = {
+				LastSwiftMigration = 0710;
+				LastSwiftUpdateCheck = 0710;
 				LastUpgradeCheck = 0700;
 				ORGANIZATIONNAME = "Rasmus Taulborg Hummelmose";
 				TargetAttributes = {

diff --git a/Example/BKExample.xcodeproj/project.xcworkspace/xcshareddata/BKExample.xcscmblueprint b/Example/BKExample.xcodeproj/project.xcworkspace/xcshareddata/BKExample.xcscmblueprint
@@ -1,4 +1,5 @@
 {
+  "DVTSourceControlWorkspaceBlueprintPrimaryRemoteRepositoryKey" : "EF50CF03AA1E23E524F182DF992B5CD2E0F67319",
   "DVTSourceControlWorkspaceBlueprintWorkingCopyRepositoryLocationsKey" : {
 
   },
@@ -8,12 +9,12 @@
   },
   "DVTSourceControlWorkspaceBlueprintIdentifierKey" : "E4650D93-BD55-45B2-9D6B-30B69C3F651C",
   "DVTSourceControlWorkspaceBlueprintWorkingCopyPathsKey" : {
-    "EF50CF03AA1E23E524F182DF992B5CD2E0F67319" : "",
-    "3AF18F9C6F5D633BAA0B3F935459E0C777C82047" : "..\/SnapKit"
+    "EF50CF03AA1E23E524F182DF992B5CD2E0F67319" : "BluetoothKit\/",
+    "3AF18F9C6F5D633BAA0B3F935459E0C777C82047" : "SnapKit\/"
   },
   "DVTSourceControlWorkspaceBlueprintNameKey" : "BKExample",
   "DVTSourceControlWorkspaceBlueprintVersion" : 204,
-  "DVTSourceControlWorkspaceBlueprintRelativePathToProjectKey" : "BKExample.xcodeproj",
+  "DVTSourceControlWorkspaceBlueprintRelativePathToProjectKey" : "Example\/BKExample.xcodeproj",
   "DVTSourceControlWorkspaceBlueprintRemoteRepositoriesKey" : [
     {
       "DVTSourceControlWorkspaceBlueprintRemoteRepositoryURLKey" : "https:\/\/github.com\/rasmusth\/SnapKit.git",

diff --git a/Example/Source/Global/Logger.swift b/Example/Source/Global/Logger.swift
@@ -45,7 +45,7 @@ internal struct Logger {
     internal static func log(string: String) {
         let date = NSDate()
         let stringWithDate = "[\(loggingDateFormatter.stringFromDate(date))] \(string)"
-        print(stringWithDate)
+        print(stringWithDate, terminator: "")
         Logger.delegate?.loggerDidLogString(stringWithDate)
     }
 

diff --git a/Example/Source/View Controllers/RemotePeripheralViewController.swift b/Example/Source/View Controllers/RemotePeripheralViewController.swift
@@ -83,7 +83,7 @@ internal class RemotePeripheralViewController: UIViewController, BKRemotePeriphe
         Logger.log("Name change: \(name)")
     }
 
-    internal func remotePeripheral(remotePeripheral: BKRemotePeripheral, didReceiveArbitraryData data: NSData) {
+    internal func remotePeripheral(remotePeripheral: BKRemotePeripheral, didSendArbitraryData data: NSData) {
         Logger.log("Received data of length: \(data.length) with hash: \(data.md5()!.hexString)")
     }
 

diff --git a/Source/BKCental.swift b/Source/BKCental.swift
@@ -37,8 +37,6 @@ public protocol BKCentralDelegate: class {
     func central(central: BKCentral, remotePeripheralDidDisconnect remotePeripheral: BKRemotePeripheral)
 }
 
-private let singleton = BKCentral()
-
 /**
     The class used to take the Bluetooth LE central role. The central discovers remote peripherals by scanning
     and connects to them. When a connection is established the central can receive data from the remote peripheral.
@@ -56,12 +54,24 @@ public class BKCentral: BKCBCentralManagerStateDelegate, BKConnectionPoolDelegat
 
     // MARK: Enums
 
+    /**
+        Errors that can occur when interacting with BKCentral objects.
+        - InterruptedByUnavailability(cause): Will be returned if Bluetooth ie. is turned off while performing an action.
+        - FailedToConnectDueToTimeout: The time out elapsed while attempting to connect to a peripheral.
+        - InternalError(underlyingError): Will be returned if any of the internal or private classes returns an unhandled error.
+    */
     public enum Error: ErrorType {
-        case InterruptedByUnavailability(BKUnavailabilityCause)
+        case InterruptedByUnavailability(cause: BKUnavailabilityCause)
         case FailedToConnectDueToTimeout
         case InternalError(underlyingError: ErrorType?)
     }
 
+    /**
+        Possible states returned by the ContinuousScanStateHandler.
+        - Stopped: The scan has come to a complete stop and won't start again by triggered manually.
+        - Scanning: The scan is currently active.
+        - Waiting: The scan is on hold due while waiting for the in-between delay to expire, after which it will start again.
+    */
     public enum ContinuousScanState {
         case Stopped
         case Scanning
@@ -70,10 +80,7 @@ public class BKCentral: BKCBCentralManagerStateDelegate, BKConnectionPoolDelegat
 
     // MARK: Properties
 
-    public class var sharedInstance: BKCentral {
-        return singleton
-    }
-
+    /// Bluetooth LE availability, derived from the underlying CBCentralManager.
     public var availability: BKAvailability? {
         if let centralManager = _centralManager {
             return BKAvailability(centralManagerState: centralManager.state)
@@ -82,25 +89,30 @@ public class BKCentral: BKCBCentralManagerStateDelegate, BKConnectionPoolDelegat
         }
     }
 
+    /// All currently connected remote peripherals.
     public var connectedRemotePeripherals: [BKRemotePeripheral] {
         return connectionPool.connectedRemotePeripherals
     }
 
+    /// The configuration the BKCentral object was started with.
     public var configuration: BKConfiguration? {
         return _configuration
     }
 
-    public var centralManager: CBCentralManager? {
-        return _centralManager
-    }
-
+    /// The delegate of the BKCentral object.
     public weak var delegate: BKCentralDelegate?
+
+    /// Current availability observers.
     public var availabilityObservers = [BKWeakAvailabilityObserver]()
 
-    private var _configuration: BKConfiguration?
+    private var centralManager: CBCentralManager? {
+        return _centralManager
+    }
+
     private let scanner = BKScanner()
-    private var continuousScanner: BKContinousScanner!
     private let connectionPool = BKConnectionPool()
+    private var _configuration: BKConfiguration?
+    private var continuousScanner: BKContinousScanner!
     private var centralManagerDelegate: BKCBCentralManagerDelegateProxy!
     private var stateMachine: BKCentralStateMachine!
     private var _centralManager: CBCentralManager!
@@ -116,6 +128,11 @@ public class BKCentral: BKCBCentralManagerStateDelegate, BKConnectionPoolDelegat
 
     // MARK: Public Functions
 
+    /**
+        Start the BKCentral object with a configuration.
+        - parameter configuration: The configuration defining which UUIDs to use when discovering peripherals.
+        - throws: Throws an InternalError if the BKCentral object is already started.
+    */
     public func startWithConfiguration(configuration: BKConfiguration) throws {
         do {
             try stateMachine.handleEvent(.Start)
@@ -129,6 +146,12 @@ public class BKCentral: BKCBCentralManagerStateDelegate, BKConnectionPoolDelegat
         }
     }
 
+    /**
+        Scan for peripherals for a limited duration of time.
+        - parameter duration: The number of seconds to scan for (defaults to 3).
+        - parameter progressHandler: A progress handler allowing you to react immediately when a peripheral is discovered during a scan.
+        - parameter completionHandler: A completion handler allowing you to react on the full result of discovered peripherals or an error if one occured.
+    */
     public func scanWithDuration(duration: NSTimeInterval = 3, progressHandler: ScanProgressHandler?, completionHandler: ScanCompletionHandler?) {
         do {
             try stateMachine.handleEvent(.Scan)
@@ -147,6 +170,14 @@ public class BKCentral: BKCBCentralManagerStateDelegate, BKConnectionPoolDelegat
         }
     }
 
+    /**
+        Scan for peripherals for a limited duration of time continuously with an in-between delay.
+        - parameter changeHandler: A change handler allowing you to react to changes in "maintained" discovered peripherals.
+        - parameter stateHandler: A state handler allowing you to react when the scanner is started, waiting and stopped.
+        - parameter duration: The number of seconds to scan for (defaults to 3).
+        - parameter inBetweenDelay: The number of seconds to wait for, in-between scans (defaults to 3).
+        - parameter errorHandler: An error handler allowing you to react when an error occurs. For now this is also called when the scan is manually interrupted.
+    */
     public func scanContinuouslyWithChangeHandler(changeHandler: ContinuousScanChangeHandler, stateHandler: ContinuousScanStateHandler?, duration: NSTimeInterval = 3, inBetweenDelay: NSTimeInterval = 3, errorHandler: ContinuousScanErrorHandler?) {
         do {
             try stateMachine.handleEvent(.Scan)
@@ -163,11 +194,20 @@ public class BKCentral: BKCBCentralManagerStateDelegate, BKConnectionPoolDelegat
         }
     }
 
+    /**
+        Interrupts the active scan session if present.
+    */
     public func interrupScan() {
         continuousScanner.interruptScan()
         scanner.interruptScan()
     }
 
+    /**
+        Connect to a remote peripheral.
+        - parameter timeout: The number of seconds the connection attempt should continue for before failing.
+        - parameter remotePeripheral: The remote peripheral to connect to.
+        - parameter completionHandler: A completion handler allowing you to react when the connection attempt succeeded or failed.
+    */
     public func connect(timeout: NSTimeInterval = 3, remotePeripheral: BKRemotePeripheral, completionHandler: ConnectCompletionHandler) {
         do {
             try stateMachine.handleEvent(.Connect)
@@ -186,6 +226,11 @@ public class BKCentral: BKCBCentralManagerStateDelegate, BKConnectionPoolDelegat
         }
     }
 
+    /**
+        Disconnects a connected peripheral.
+        - parameter remotePeripheral: The peripheral to disconnect.
+        - throws: Throws an InternalError if the remote peripheral is not currently connected.
+    */
     public func disconnectRemotePeripheral(remotePeripheral: BKRemotePeripheral) throws {
         do {
             try connectionPool.disconnectRemotePeripheral(remotePeripheral)
@@ -194,6 +239,10 @@ public class BKCentral: BKCBCentralManagerStateDelegate, BKConnectionPoolDelegat
         }
     }
 
+    /**
+        Stops the BKCentral object.
+        - throws: Throws an InternalError if the BKCentral object isn't already started.
+    */
     public func stop() throws {
         do {
             try stateMachine.handleEvent(.Stop)
@@ -256,7 +305,7 @@ public class BKCentral: BKCBCentralManagerStateDelegate, BKConnectionPoolDelegat
 
     // MARK: BKConnectionPoolDelegate
 
-    func connectionPool(connectionPool: BKConnectionPool, remotePeripheralDidDisconnect remotePeripheral: BKRemotePeripheral) {
+    internal func connectionPool(connectionPool: BKConnectionPool, remotePeripheralDidDisconnect remotePeripheral: BKRemotePeripheral) {
         delegate?.central(self, remotePeripheralDidDisconnect: remotePeripheral)
     }
 

diff --git a/Source/BKConfiguration.swift b/Source/BKConfiguration.swift
@@ -25,13 +25,23 @@
 import Foundation
 import CoreBluetooth
 
+/**
+    Class that represents a configuration used when starting a BKCentral object.
+*/
 public class BKConfiguration {
 
     // MARK: Properties
 
+    /// The UUID for the service used to send data. This should be unique to your applications.
     public let dataServiceUUID: CBUUID
+
+    /// The UUID for the characteristic used to send data. This should be unique to your application.
     public var dataServiceCharacteristicUUID: CBUUID
+
+    /// Data used to indicate that no more data is coming when communicating.
     public var endOfDataMark: NSData
+
+    /// Data used to indicate that a transfer was cancellen when communicating.
     public var dataCancelledMark: NSData
 
     internal var serviceUUIDs: [CBUUID] {
@@ -40,8 +50,8 @@ public class BKConfiguration {
     }
 
     // MARK: Initialization
-    
-    public init(dataServiceUUID: NSUUID, dataServiceCharacteristicUUID: NSUUID, additionalServices: [CBMutableService]? = nil) {
+
+    public init(dataServiceUUID: NSUUID, dataServiceCharacteristicUUID: NSUUID) {
         self.dataServiceUUID = CBUUID(NSUUID: dataServiceUUID)
         self.dataServiceCharacteristicUUID = CBUUID(NSUUID: dataServiceCharacteristicUUID)
         endOfDataMark = "EOD".dataUsingEncoding(NSUTF8StringEncoding)!

diff --git a/Source/BKDiscoveriesChange.swift b/Source/BKDiscoveriesChange.swift
@@ -32,11 +32,19 @@ public func ==(lhs: BKDiscoveriesChange, rhs: BKDiscoveriesChange) -> Bool {
     }
 }
 
+/**
+    Change in available discoveries.
+    - Insert: A new discovery.
+    - Remove: A discovery has become unavailable.
+
+    Cases without associated discoveries can be used to validate whether or not a change is and insert or a remove.
+*/
 public enum BKDiscoveriesChange: Equatable {
 
     case Insert(discovery: BKDiscovery?)
     case Remove(discovery: BKDiscovery?)
 
+    /// The discovery associated with the change.
     public var discovery: BKDiscovery! {
         switch self {
             case .Insert(let discovery): return discovery

diff --git a/Source/BKDiscovery.swift b/Source/BKDiscovery.swift
@@ -28,16 +28,25 @@ public func ==(lhs: BKDiscovery, rhs: BKDiscovery) -> Bool {
     return lhs.remotePeripheral == rhs.remotePeripheral
 }
 
+/**
+    A discovery made while scanning, containing a peripheral, the advertisement data and RSSI.
+*/
 public struct BKDiscovery: Equatable {
 
     // MARK: Properties
 
+    /// The advertised name derived from the advertisement data.
     public var localName: String? {
         return advertisementData[CBAdvertisementDataLocalNameKey] as? String
     }
 
+    /// The data advertised while the discovery was made.
     public let advertisementData: [String: AnyObject]
+
+    /// The remote peripheral that was discovered.
     public let remotePeripheral: BKRemotePeripheral
+
+    /// The [RSSI (Received signal strength indication)](https://en.wikipedia.org/wiki/Received_signal_strength_indication) value when the discovery was made.
     public let RSSI: Int
 
     // MARK: Initialization