Merge branch 'develop'

Framework/Source Files/Advertisement/AdvertisementService.swift

@@ -10,7 +10,7 @@ import CoreBluetooth
 internal final class AdvertisementService: NSObject {
 
     /// Peripheral manager used for advertisement.
-    /// SeeAlso: CBPeripheralManager
+    /// - SeeAlso: `CBPeripheralManager`
     private lazy var peripheralManager = CBPeripheralManager(delegate: self, queue: nil)
 
     /// Boolean value indicating whether device should advertise.
@@ -61,7 +61,7 @@ internal final class AdvertisementService: NSObject {
 
 extension AdvertisementService: CBPeripheralManagerDelegate {
 
-    /// SeeAlso: CBPeripheralManagerDelegate
+    /// - SeeAlso: `CBPeripheralManagerDelegate`
     func peripheralManagerDidUpdateState(_ peripheral: CBPeripheralManager) {
         do {
             try peripheral.validateState()
@@ -74,7 +74,7 @@ extension AdvertisementService: CBPeripheralManagerDelegate {
         }
     }
 
-    /// SeeAlso: CBPeripheralManagerDelegate
+    /// - SeeAlso: `CBPeripheralManagerDelegate`
     func peripheralManagerDidStartAdvertising(_ peripheral: CBPeripheralManager, error: Error?) {
         if let error = error {
             errorHandler?(.otherError(error))
@@ -83,14 +83,14 @@ extension AdvertisementService: CBPeripheralManagerDelegate {
         self.peripheral?.configuration.services.map({ $0.assignAdvertisementService() }).forEach(peripheralManager.add(_:))
     }
 
-    /// SeeAlso: CBPeripheralManagerDelegate
+    /// - SeeAlso: `CBPeripheralManagerDelegate`
     func peripheralManager(_ peripheral: CBPeripheralManager, didAdd service: CBService, error: Error?) {
         if let error = error {
             errorHandler?(.otherError(error))
         }
     }
-    
-    /// SeeAlso: CBPeripheralManagerDelegate
+
+    /// - SeeAlso: `CBPeripheralManagerDelegate`
     func peripheralManager(_ peripheral: CBPeripheralManager, didReceiveRead request: CBATTRequest) {
         let rawCharacteristic = request.characteristic
         guard let characteristic = self.peripheral?.configuration.characteristic(matching: rawCharacteristic) else { return }
@@ -99,7 +99,7 @@ extension AdvertisementService: CBPeripheralManagerDelegate {
         peripheral.respond(to: request, withResult: .success)
     }
 
-    /// SeeAlso: CBPeripheralManagerDelegate
+    /// - SeeAlso: `CBPeripheralManagerDelegate`
     func peripheralManager(_ peripheral: CBPeripheralManager, didReceiveWrite requests: [CBATTRequest]) {
         requests.forEach { request in
             let rawCharacteristic = request.characteristic
@@ -109,12 +109,12 @@ extension AdvertisementService: CBPeripheralManagerDelegate {
         }
     }
 
-    /// SeeAlso: CBPeripheralManagerDelegate
+    /// - SeeAlso: `CBPeripheralManagerDelegate`
     func peripheralManager(_ peripheral: CBPeripheralManager, central: CBCentral, didSubscribeTo characteristic: CBCharacteristic) {
         subsribedCentrals.append(central)
     }
 
-    /// SeeAlso: CBPeripheralManagerDelegate
+    /// - SeeAlso: `CBPeripheralManagerDelegate`
     func peripheralManager(_ peripheral: CBPeripheralManager, central: CBCentral, didUnsubscribeFrom characteristic: CBCharacteristic) {
         guard let index = subsribedCentrals.index(where: { $0 === central }) else { return }
         subsribedCentrals.remove(at: index)

Framework/Source Files/Advertisement/BluetoothAdvertisement.swift

@@ -9,7 +9,7 @@ import Foundation
 public final class BluetoothAdvertisement {
 
     /// Advertisement service.
-    /// SeeAlso: AdvertisementService
+    /// - SeeAlso: `AdvertisementService`
     private lazy var advertisementService = AdvertisementService()
 
     /// A singleton instance.
@@ -19,10 +19,12 @@ public final class BluetoothAdvertisement {
     public init() { }
 
     /// Start advertising peripheral with parameters given by a configuration of passed peripheral.
-    /// Parameter peripheral: a peripheral containing configuration with specified services and characteristics.
-    /// Parameter errorHandler: an error handler. Will be called only after unsuccesfull advertisement setup.
-    /// SeeAlso: AdvertisementError
-    /// SeeAlso: Peripheral
+    ///
+    /// - Parameters:
+    ///     - peripheral: a peripheral containing configuration with specified services and characteristics.
+    ///     - errorHandler: an error handler. Will be called only after unsuccessfull advertisement setup.
+    /// - SeeAlso: `AdvertisementError`
+    /// - SeeAlso: `Peripheral`
     public func advertise(peripheral: Peripheral<Advertisable>, errorHandler: ((AdvertisementError) -> ())?) {
         advertisementService.startAdvertising(peripheral, errorHandler: errorHandler)
     }
@@ -34,11 +36,13 @@ public final class BluetoothAdvertisement {
 
     /// Updates a value for specified characteristic with data.
     /// After the request a notify will be called on all subscribed centrals.
-    /// Parameter value: a data to update on characteristic.
-    /// Parameter characteristic: specified characteristic to be updated.
-    /// Parameter errorHandler: an error handler called if data update fails.
-    /// SeeAlso: AdvertisementError
-    /// SeeAlso: Characteristic
+    ///
+    /// - Parameters:
+    ///     - command: a comand to update on characteristic.
+    ///     - characteristic: specified characteristic to be updated.
+    ///     - errorHandler: an error handler called if data update fails.
+    /// - SeeAlso: `AdvertisementError`
+    /// - SeeAlso: `Characteristic`
     public func update(_ command: Command, characteristic: Characteristic, errorHandler: @escaping (AdvertisementError) -> (Void)) {
         do {
             try advertisementService.updateValue(command.convertedData(), characteristic: characteristic, errorHandler: errorHandler)

Framework/Source Files/Command/Command.swift

@@ -8,8 +8,7 @@ import Foundation
 
 /// Command enum - a handy wrapper for creating requests to peripheral devices.
 /// Handles creation of data with length according to passed parameter type, also creates data straight from hexadecimal
-/// string with exact the same value. If none of the cases matches needed type, use .data(Data) case where Data object can be
-/// passed directly.
+/// string with exact the same value. If none of the cases matches needed type, use .data(Data) case where Data object can be passed directly.
 public enum Command {
     case int8(UInt8)
     case int16(UInt16)

Framework/Source Files/Connection/BluetoothConnection.swift

@@ -32,10 +32,12 @@ public final class BluetoothConnection: NSObject {
     }
 
     /// Primary method used to connect to a device. Can be called multiple times to connect more than on device at the same time.
-    /// - Parameter peripheral: a configured device you wish to connect to.
-    /// - Parameter handler: a completion handler called upon succesfull connection or a error.
-    /// - SeeAlso: BluetoothConnection.ConnectionError
-    /// - SeeAlso: Peripheral
+    ///
+    /// - Parameters:
+    ///     - peripheral: a configured device you wish to connect to.
+    ///     - handler: a completion handler called upon successfull connection or a error.
+    /// - SeeAlso: `BluetoothConnection.ConnectionError`
+    /// - SeeAlso: `Peripheral`
     public func connect(_ peripheral: Peripheral<Connectable>, handler: ((ConnectionError?) -> ())?) {
         guard !peripheral.isConnected else {
             handler?(.deviceAlreadyConnected)
@@ -51,8 +53,8 @@ public final class BluetoothConnection: NSObject {
         }
     }
 
-    /// Primary method to disconnect a device. If it's not yet connected it'll be removed from connection queue, and
-    /// connection attempts will stop.
+    /// Primary method to disconnect a device. If it's not yet connected it'll be removed from connection queue, and connection attempts will stop.
+    ///
     /// - Parameter peripheral: a peripheral you wish to disconnect. Should be exactly the same instance that was used for connection.
     /// - Throws: BluetoothConnection.ConnectionError in case there was a disconnection problem
     /// - SeeAlso: BluetoothConnection.DisconnectionError

Framework/Source Files/Connection/ConnectionService.swift

@@ -126,7 +126,7 @@ extension ConnectionService: CBCentralManagerDelegate {
         central.connect(peripheral, options: connectionOptions)
     }
 
-    /// Called upon a succesfull peripheral connection.
+    /// Called upon a successfull peripheral connection.
     /// - SeeAlso: CBCentralManagerDelegate
     public func centralManager(_ central: CBCentralManager, didConnect peripheral: CBPeripheral) {
         guard let connectingPeripheral = peripherals.filter({ $0.peripheral === peripheral }).first else { return }

Framework/Source Files/Extensions/CBManager.swift

@@ -7,7 +7,8 @@ import Foundation
 import CoreBluetooth
 
 internal extension CBManager {
-
+
+    /// Validates the current state of CBManager class to determine if Bluetooth is not supported on this device or is turned off or unavailable for some other reason.
     func validateState() throws {
         switch state {
         case .poweredOff, .resetting, .unauthorized:

Framework/Source Files/Extensions/CBUUID.swift

@@ -15,8 +15,9 @@ internal extension CBUUID {
 
     /// Convenience initializer, a wrapper for default init(string: String) method with error handling, not crashing
     /// like default one.
-    /// - Parameter uuidString - a String wished to be converted into CBUIID.
-    /// - Throws: CreationError.invalidString if passed String is not valid.
+    ///
+    /// - Parameter uuidString: a String wished to be converted into CBUIID.
+    /// - Throws: `CreationError.invalidString` if passed String is not valid.
     convenience internal init(uuidString: String) throws {
         guard let uuid = UUID(uuidString: uuidString) else {
             guard uuidString.isValidShortenedUUID() else { throw CreationError.invalidString }

Framework/Source Files/Model/Characteristic.swift

@@ -29,11 +29,12 @@ public class Characteristic {
     internal let bluetoothUUID: CBUUID
 
     /// Initializes a new instance of Characteristic. It's failable if passed UUID String is not parseable to UUID standards.
-    /// - Parameter uuid: UUID of desired service, should be parseable to CBUUID in order for the initializer to work.
-    /// - Parameter shouldObserveNotification: indicates if this characteristic should notify when it's value changes. Note that this
-    ///   will happen only when characteristic properties include Notify. False by default.
+    ///
+    /// - Parameters:
+    ///     - uuid: UUID of desired service, should be parseable to CBUUID in order for the initializer to work.
+    ///     - shouldObserveNotification: indicates if this characteristic should notify when it's value changes. Note that this will happen only when characteristic properties include Notify. False by default.
     /// - Throws: CBUUID.CreationError
-    /// - SeeAlso: CBUUID.CreationError
+    /// - SeeAlso: `CBUUID.CreationError`
     public init(uuid: String, shouldObserveNotification: Bool = false) throws {
         self.bluetoothUUID = try CBUUID(uuidString: uuid)
         self.uuid = uuid

Framework/Source Files/Model/Configuration.swift

@@ -18,10 +18,12 @@ public struct Configuration {
 
     /// Creates a new instance of configuration containing Services desired peripheral should contain.
     /// Used to initialize a Peripheral instance.
-    /// - Parameter services: An array of Services wished to use.
-    /// - Parameter advertisement: UUID of desired peripheral that is sepcified in adverisement header.
+    ///
+    /// - Parameters:
+    ///     - services: An array of Services wished to use.
+    ///     - advertisement: UUID of desired peripheral that is specified in advertisement header.
     /// - Throws: CBUUID.CreationError
-    /// - SeeAlso: CBUUID.CreationError
+    /// - SeeAlso: `CBUUID.CreationError`
     public init(services: [Service], advertisement: String) throws {
         advertisementUUID = try CBUUID(uuidString: advertisement)
         self.services = services

Framework/Source Files/Model/Peripheral/AdvertisablePeripheral.swift

@@ -7,7 +7,12 @@ import Foundation
 import CoreBluetooth
 
 public extension Peripheral where Type == Advertisable {
-
+
+    /// Creates a new instance of Peripheral that will be used for advertisement purposes.
+    ///
+    /// - Parameters:
+    ///   - configuration: a specification of the peripheral that you are willing to advertise wrapped in Configuration object instance.
+    ///   - advertisementData: a data that should be put in Bluetooth LE advertisement header. Please note that iPhones don't allow some keys there, so they won't be advertised even if set properly.
     public convenience init(configuration: Configuration, advertisementData: [AdvertisementData]) {
         self.init(configuration: configuration, deviceIdentifier: nil, advertisementData: advertisementData)
     }

Framework/Source Files/Model/Peripheral/ConnectablePeripheral.swift

@@ -14,10 +14,11 @@ public extension Peripheral where Type == Connectable {
     }
 
     /// Deafult initializer for Perpipheral.
-    /// - Parameter configuration: proviously created configuration containing all desired services and characteristics.
-    /// - Parameter deviceIdentifier: optional parameter. If device identifier is cached locally than it should be passed here.
-    ///   When set, connection to peripheral is much quicker.
-    /// - SeeAlso: Configuration
+    ///
+    /// - Parameters:
+    ///     - configuration: previously created configuration containing all desired services and characteristics.
+    ///     - deviceIdentifier: optional parameter. If device identifier is cached locally then it should be passed here. When set, connection to peripheral is much quicker.
+    /// - SeeAlso: `Configuration`
     public convenience init(configuration: Configuration, deviceIdentifier: String? = nil) {
         self.init(configuration: configuration, deviceIdentifier: deviceIdentifier, advertisementData: nil)
     }
@@ -29,12 +30,14 @@ public extension Peripheral where Type == Connectable {
     }
 
     /// Method used for writing to the peripheral after it's connected.
-    /// - Parameter command: a command to write to the device.
-    /// - Parameter characteristic: a characteristic the command should be directed to.
-    /// - Parameter handler: a completion handler indicating if reuqest was succesfull.
-    /// - SeeAlso: Command
-    /// - SeeAlso: Characteristic
-    /// - SeeAlso: Peripheral.TransmissionError
+    ///
+    /// - Parameters:
+    ///     - command: a command to write to the device.
+    ///     - characteristic: a characteristic the command should be directed to.
+    ///     - handler: a completion handler indicating if reuqest was successfull.
+    /// - SeeAlso: `Command`
+    /// - SeeAlso: `Characteristic`
+    /// - SeeAlso: `Peripheral.TransmissionError`
     public func write(command: Command, characteristic: Characteristic, handler: ((TransmissionError?) -> ())?) {
         do {
             let unwrapped = try validateForTransmission(characteristic, action: .write)
@@ -50,10 +53,12 @@ public extension Peripheral where Type == Connectable {
     }
 
     /// Method used to perform read request from peripheral after it's connected.
-    /// - Parameter characteristic: a characteristic you wish to read.
-    /// - Parameter handler: completion handler returning Data retrieved from characteristic or error if it failed.
-    /// - SeeAlso: Characteristic
-    /// - SeeAlso: Peripheral.TransmissionError
+    ///
+    /// - Parameters:
+    ///     - characteristic: a characteristic you wish to read.
+    ///     - handler: completion handler returning Data retrieved from characteristic or error if it failed.
+    /// - SeeAlso: `Characteristic`
+    /// - SeeAlso: `Peripheral.TransmissionError`
     public func read(_ characteristic: Characteristic, handler: ((Data?, TransmissionError?) -> ())?) {
         do {
             let unwrapped = try validateForTransmission(characteristic, action: .read)

Framework/Source Files/Model/Peripheral/Peripheral.swift

@@ -59,7 +59,7 @@ public final class Peripheral<Type: PeripheralType>: NSObject, CBPeripheralDeleg
     internal var readHandler: ((Data?, TransmissionError?) -> ())?
 
     /// Called after reading data from characteristic.
-    /// - SeeAlso: CBPeripheralDelegate
+    /// - SeeAlso: `CBPeripheralDelegate`
     /// This should be moved to an extension in Swift 5 according to: https://github.com/apple/swift-evolution/blob/master/proposals/0143-conditional-conformances.md feature.
     public func peripheral(_ peripheral: CBPeripheral, didWriteValueFor characteristic: CBCharacteristic, error: Error?) {
         defer {
@@ -76,7 +76,7 @@ public final class Peripheral<Type: PeripheralType>: NSObject, CBPeripheralDeleg
     /// Called in two cases:
     /// 1) After performing read request from peripheral.
     /// 2) After peripheral updates value for characteristic with notify turned on.
-    /// - SeeAlso: CBPeripheralDelegate
+    /// - SeeAlso: `CBPeripheralDelegate`
     public func peripheral(_ peripheral: CBPeripheral, didUpdateValueFor characteristic: CBCharacteristic, error: Error?) {
         defer {
             readHandler = nil

Framework/Source Files/Model/Service.swift

@@ -22,12 +22,13 @@ public class Service {
     internal var advertisementService: CBMutableService?
 
     /// Initializes a new instance of Service. It's failable if passed UUID String is not parseable to UUID standards.
-    /// - Parameter uuid: UUID of desired service, should be parseable to CBUUID in order for the initializer to work.
-    /// - Parameter characteristics: a list of Characteristic desired Service should contain. Please note that this list does not
-    /// have to be exhaustive and contain all characteristics desired service contains on the peripheral. Pass only ones
+    ///
+    /// - Parameters:
+    ///     - uuid: UUID of desired service, should be parseable to CBUUID in order for the initializer to work.
+    ///     - characteristics: a list of Characteristic desired Service should contain. Please note that this list does not have to be exhaustive and contain all characteristics desired service contains on the peripheral. Pass only ones
     /// you wish to use.
     /// - Throws: CBUUID.CreationError
-    /// - SeeAlso: CBUUID.CreationError
+    /// - SeeAlso: `CBUUID.CreationError`
     public init(uuid: String, characteristics: [Characteristic]) throws {
         self.bluetoothUUID = try CBUUID(uuidString: uuid)
         self.uuid = uuid

Readme.md

@@ -1,3 +1,7 @@
+![](./logo.png)
+
+<br/>
+
 ![](https://img.shields.io/badge/swift-4.2-orange.svg)
 ![](https://img.shields.io/github/release/netguru/BlueSwift.svg)
 ![](https://img.shields.io/badge/carthage-compatible-green.svg)

Unit Tests/CommandTests.swift

@@ -28,7 +28,7 @@ class CommandTests: XCTestCase {
 
         do {
             _ = try improperString.hexDecodedData()
-            XCTFail("Improper string succesfull parse should throw an error.")
+            XCTFail("Improper string successfull parse should throw an error.")
         }
         catch let error {
             guard let error = error as? Command.ConversionError else {