Documentation (#61)

* Fix reading wrong property from CONNACK for pingreq interval

* Add build documentation scripts

* Add comments for properties

* Add comments to MQTTReason

* Comments for connection return values

* More comments

Author: adam-fowler

Sources/MQTTNIO/MQTTClient.swift

@@ -11,6 +11,18 @@ import NIOSSL
 import NIOTransportServices
 
 /// Swift NIO MQTT Client
+///
+/// Main public interface providing methods for connecting to a server, publishing
+/// and subscribing to MQTT topics
+/// ```
+/// let client = MQTTClient(
+///     host: "mqtt.eclipse.org",
+///     port: 1883,
+///     identifier: "My Client",
+///     eventLoopGroupProvider: .createNew
+///     )
+///     try client.connect().wait()
+/// ```
 public final class MQTTClient {
     /// EventLoopGroup used by MQTTCllent
     public let eventLoopGroup: EventLoopGroup
@@ -232,7 +244,7 @@ public final class MQTTClient {
         return self.disconnect(packet: MQTTDisconnectPacket())
     }
 
-    /// Return is client has an active connection to broker
+    /// Return if client has an active connection to broker
     public func isActive() -> Bool {
         return self.connection?.channel.isActive ?? false
     }
@@ -383,8 +395,8 @@ extension MQTTClient {
         for property in connack.properties.properties {
             // alter pingreq interval based on session expiry returned from server
             if let connection = self.connection {
-                if case .sessionExpiryInterval(let sessionExpiryInterval) = property {
-                    let pingTimeout = TimeAmount.seconds(max(Int64(sessionExpiryInterval - 5), 5))
+                if case .serverKeepAlive(let keepAliveInterval) = property {
+                    let pingTimeout = TimeAmount.seconds(max(Int64(keepAliveInterval - 5), 5))
                     connection.updatePingreqTimeout(pingTimeout)
                 }
             }

Sources/MQTTNIO/MQTTClientV5.swift

@@ -1,6 +1,7 @@
 import NIO
 
 extension MQTTClient {
+    /// Provides implementations of functions that expose MQTT Version 5.0 features
     public struct V5 {
         let client: MQTTClient
 

Sources/MQTTNIO/MQTTConfiguration.swift

@@ -4,6 +4,7 @@ import NIOSSL
 #endif
 
 extension MQTTClient {
+    /// Version of MQTT server to connect to
     public enum Version {
         case v3_1_1
         case v5_0
@@ -25,6 +26,7 @@ extension MQTTClient {
 
     /// Configuration for MQTTClient
     public struct Configuration {
+        /// Initialize MQTTClient configuration struct
         public init(
             version: Version = .v3_1_1,
             disablePing: Bool = false,
@@ -59,7 +61,7 @@ extension MQTTClient {
             self.webSocketMaxFrameSize = webSocketMaxFrameSize
         }
 
-        /// disable the sending of pingreq messages
+        /// Version of MQTT server client is connecting to
         public let version: Version
         /// disable the sending of pingreq messages
         public let disablePing: Bool

Sources/MQTTNIO/MQTTCoreTypesV5.swift

@@ -12,7 +12,7 @@ public struct MQTTConnackV5 {
 
 /// MQTT V5 ACK information. Returned with PUBACK, PUBREL
 public struct MQTTAckV5 {
-    /// MQTT v5 disconnection reason
+    /// MQTT v5 reason code
     public let reason: MQTTReasonCode
     /// MQTT v5 properties
     public let properties: MQTTProperties
@@ -25,9 +25,13 @@ public struct MQTTAckV5 {
 
 /// MQTT SUBSCRIBE packet parameters.
 public struct MQTTSubscribeInfoV5 {
+    /// Retain handling options
     public enum RetainHandling: UInt8 {
+        /// always send retain message
         case sendAlways = 0
+        /// send retain if new
         case sendIfNew = 1
+        /// do not send retain message
         case doNotSend = 2
     }
 
@@ -65,7 +69,7 @@ public struct MQTTSubscribeInfoV5 {
 ///
 /// Contains data returned in subscribe/unsubscribe ack packets
 public struct MQTTSubackV5 {
-    /// MQTT v5 disconnection reason
+    /// MQTT v5 subscription reason code
     public let reasons: [MQTTReasonCode]
     /// MQTT v5 properties
     public let properties: MQTTProperties
@@ -80,7 +84,7 @@ public struct MQTTSubackV5 {
 ///
 /// Contains data returned in subscribe/unsubscribe ack packets
 public struct MQTTAuthV5 {
-    /// MQTT v5 disconnection reason
+    /// MQTT v5 authentication reason code
     public let reason: MQTTReasonCode
     /// MQTT v5 properties
     public let properties: MQTTProperties

Sources/MQTTNIO/MQTTError.swift

@@ -1,12 +1,20 @@
 /// MQTTClient errors
 public enum MQTTError: Error {
+    /// Value returned in connection error
     public enum ConnectionReturnValue: UInt8 {
+        /// connection was accepted
         case accepted = 0
+        /// The Server does not support the version of the MQTT protocol requested by the Client.
         case unacceptableProtocolVersion = 1
+        /// The Client Identifier is a valid string but is not allowed by the Server.
         case identifierRejected = 2
+        /// The MQTT Server is not available.
         case serverUnavailable = 3
+        /// The Server does not accept the User Name or Password specified by the Client
         case badUserNameOrPassword = 4
+        /// The client is not authorized to connect
         case notAuthorized = 5
+        /// Return code was unrecognised
         case unrecognizedReturnValue = 0xFF
     }
 

Sources/MQTTNIO/MQTTProperties.swift

@@ -2,33 +2,65 @@ import NIO
 
 /// MQTT v5.0 properties. A property consists of a identifier and a value
 public struct MQTTProperties {
+    /// MQTT Property
     public enum Property: Equatable {
+        /// Payload format: 0 = bytes, 1 = UTF8 string (available for PUBLISH)
         case payloadFormat(UInt8)
+        /// Message expiry indicates the lifetime of the message (available for PUBLISH)
         case messageExpiry(UInt32)
+        /// String describing the content of the message eg "application/json" (available for PUBLISH)
         case contentType(String)
+        /// Response topic used in request/response interactions (available for PUBLISH)
         case responseTopic(String)
+        /// Correlation data used to id a request/response in request/response interactions (available for PUBLISH)
         case correlationData(ByteBuffer)
+        /// Subscription identifier set in SUBSCRIBE packet and included in related PUBLISH packet
+        /// (available for PUBLISH, SUBSCRIBE)
         case subscriptionIdentifier(UInt)
+        /// Interval before session expires (available for CONNECT, CONNACK, DISCONNECT)
         case sessionExpiryInterval(UInt32)
+        /// Client identifier assigned to client if they didn't provide one (available for CONNACK)
         case assignedClientIdentifier(String)
+        /// Indication to client on how long server will keep connection without activity (available for CONNACK)
         case serverKeepAlive(UInt16)
+        /// String indicating the authentication method to use (available for CONNECT, CONNACK, AUTH)
         case authenticationMethod(String)
+        /// Data used in authentication (available for CONNECT, CONNACK, AUTH)
         case authenticationData(ByteBuffer)
+        /// Request that server sends a reason string in its CONNACK or DISCONNECT packets (available for CONNECT)
         case requestProblemInformation(UInt8)
+        /// Interval to wait before publishing connect will message (available for CONNECT will)
         case willDelayInterval(UInt32)
+        /// Request response information from server (available for CONNECT)
         case requestResponseInformation(UInt8)
+        /// Response information from server. Commonly used to pass a globally unique portion
+        /// of the topic tree for this client (available for CONNACK)
         case responseInformation(String)
+        /// Server uses serverReference in CONNACK to indicate to either use another server or that the server has moved
+        /// (available for CONNACK)
         case serverReference(String)
+        /// String representing the reason associated with this response (available for CONNACK,
+        /// PUBACK, PUBREC, PUBREL, PUBCOMP, SUBACK, UNSUBACK, DISCONNECT, AUTH)
         case reasonString(String)
+        /// Maximum number of PUBLISH, PUBREL messages that can be sent without receiving a response (available for CONNECT, CONNACK)
         case receiveMaximum(UInt16)
+        /// Maximum number for topic alias (available for CONNECT, CONNACK)
         case topicAliasMaximum(UInt16)
+        /// Topic alias. Use instead of full topic name to reduce packet size (available for PUBLISH)
         case topicAlias(UInt16)
+        /// Maximum QoS supported by server (available for CONNACK)
         case maximumQoS(MQTTQoS)
+        /// Does server support retained publish packets (available for CONNACK)
         case retainAvailable(UInt8)
+        /// User property, key and value (available for all packets)
         case userProperty(String, String)
+        /// Maximum packet size supported (available for CONNECT, CONNACK)
         case maximumPacketSize(UInt32)
+        /// Does server support wildcard subscription (available for CONNACK)
         case wildcardSubscriptionAvailable(UInt8)
+        /// Does server support subscription identifiers (available for CONNACK)
         case subscriptionIdentifierAvailable(UInt8)
+        /// Does server support shared subscriptions (available for CONNACK)
         case sharedSubscriptionAvailable(UInt8)
     }
 

Sources/MQTTNIO/MQTTReason.swift

@@ -1,49 +1,97 @@
 /// MQTT v5.0 reason codes. A reason code is a one byte unsigned value that indicates the result of an operation.
 /// Reason codes less than 128 are considered successful. Codes greater than or equal to 128 are considered
-/// a failure
+/// a failure. These are returned by CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, DISCONNECT and
+/// AUTH packets
 public enum MQTTReasonCode: UInt8 {
+    /// Success (available for all). For SUBACK mean QoS0 is available
     case success = 0
+    /// The subscription is accepted and the maximum QoS sent will be QoS 1. This might be a lower QoS than was requested.
     case grantedQoS1 = 1
+    /// The subscription is accepted and any received QoS will be sent to this subscription.
     case grantedQoS2 = 2
+    /// The Client wishes to disconnect but requires that the Server also publishes its Will Message.
     case disconnectWithWill = 4
+    /// The PUBLISH message is accepted but there are no subscribers. This is sent only by the Server. If the Server knows that
+    /// there are no matching subscribers, it MAY use this Reason Code instead of 0x00 (Success).
     case noMatchingSubscriber = 16
+    /// No matching Topic Filter is being used by the Client.
     case noSubscriptionExisted = 17
+    /// Continue the authentication with another step
     case continueAuthentication = 24
+    /// Initiate a re-authentication
     case reAuthenticate = 25
+    /// Unaccpeted and the Server either does not wish to reveal the reason or none of the other Reason Codes apply.
     case unspecifiedError = 128
+    /// Data within the packet could not be correctly parsed.
     case malformedPacket = 129
+    /// Data in the packet does not conform to this specification.
     case protocolError = 130
+    /// Packet is valid but the server does not accept it
     case implementationSpecificError = 131
+    /// The Server does not support the version of the MQTT protocol requested by the Client.
     case unsupportedProtocolVersion = 132
+    /// The Client Identifier is a valid string but is not allowed by the Server.
     case clientIdentifierNotValid = 133
+    /// The Server does not accept the User Name or Password specified by the Client
     case badUsernameOrPassword = 134
+    /// The client is not authorized to do this
     case notAuthorized = 135
+    /// The MQTT Server is not available.
     case serverUnavailable = 136
+    /// The Server is busy. Try again later.
     case serverBusy = 137
+    /// This Client has been banned by administrative action. Contact the server administrator.
     case banned = 138
+    /// The Server is shutting down.
     case serverShuttingDown = 139
+    /// The authentication method is not supported or does not match the authentication method currently in use.
     case badAuthenticationMethod = 140
+    /// The Connection is closed because no packet has been received for 1.5 times the Keepalive time.
     case keepAliveTimeout = 141
+    /// Another Connection using the same ClientID has connected causing this Connection to be closed.
     case sessionTakenOver = 142
+    /// The Topic Filter is correctly formed but is not allowed for this Client.
     case topicFilterInvalid = 143
+    /// The Topic Name is not malformed, but is not accepted by this Client or Server.
     case topicNameInvalid = 144
+    /// The specified Packet Identifier is already in use. This might indicate a mismatch in the Session State between the Client and Server.
     case packetIdentifierInUse = 145
+    /// The Packet Identifier is not known. This is not an error during recovery, but at other times indicates a mismatch between
+    /// the Session State on the Client and Server.
     case packetIdentifierNotFound = 146
+    /// The Client or Server has received more than Receive Maximum publication for which it has not sent PUBACK or PUBCOMP.
     case receiveMaximumExceeded = 147
+    /// The Client or Server has received a PUBLISH packet containing a Topic Alias which is greater than the Maximum Topic Alias it
+    /// sent in the CONNECT or CONNACK packet.
     case topicAliasInvalid = 148
+    /// The packet exceeded the maximum permissible size.
     case packetTooLarge = 149
+    /// The received data rate is too high.
     case messageRateTooHigh = 150
+    /// An implementation or administrative imposed limit has been exceeded.
     case quotaExceeeded = 151
+    /// The Connection is closed due to an administrative action.
     case administrativeAction = 152
+    /// The PUBLISH payload format does not match the one specified in the Payload Format Indicator.
     case payloadFormatInvalid = 153
+    /// The Server does not support retained messages, and retain was set to 1.
     case retainNotSupported = 154
+    /// The Server does not support the QoS set
     case qosNotSupported = 155
+    /// The Client should temporarily use another server.
     case useAnotherServer = 156
+    /// The Client should permanently use another server.
     case serverMoved = 157
+    /// The Server does not support Shared Subscriptions for this Client.
     case sharedSubscriptionsNotSupported = 158
+    /// The connection rate limit has been exceeded.
     case connectionRateExceeeded = 159
+    /// The maximum connection time authorized for this connection has been exceeded.
     case maximumConnectTime = 160
+    /// The Server does not support Subscription Identifiers; the subscription is not accepted.
     case subscriptionIdentifiersNotSupported = 161
+    /// The Server does not support Wildcard Subscriptions; the subscription is not accepted.
     case wildcardSubscriptionsNotSupported = 162
+    /// Reason code was unrecognised
     case unrecognisedReason = 255
 }

scripts/build-docs.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+
+set -eux
+
+PROJECT=${1:-}
+CWD=$(pwd)
+TEMP_DIR=$(mktemp -d)
+
+get_latest_version() {
+    RELEASE_REVISION=$(git rev-list --tags --max-count=1)
+    echo $(git describe --tags "$RELEASE_REVISION")
+}
+
+build_docs() {
+    VERSION=$(get_latest_version)
+    jazzy \
+        --clean \
+        --author "Adam Fowler" \
+        --author_url https://github.com/adam-fowler \
+        --github_url https://github.com/adam-fowler/mqtt-nio \
+        --module-version "$VERSION" \
+        --output "$CWD"/docs/
+}
+
+build_docs

scripts/commit-docs.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+set -eux
+
+FOLDER=current
+SUBFOLDER=${1:-}
+
+# stash everything that isn't in docs, store result in STASH_RESULT
+STASH_RESULT=$(git stash push -- ":(exclude)docs")
+# get branch name
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+REVISION_HASH=$(git rev-parse HEAD)
+
+git checkout gh-pages
+if [[ -z "$SUBFOLDER" ]]; then
+    # copy contents of docs to docs/current replacing the ones that are already there
+    rm -rf "$FOLDER"
+    mv docs/ "$FOLDER"/
+    # commit
+    git add --all "$FOLDER"
+else
+    # copy contents of subfolder of docs to docs/current replacing the ones that are already there
+    rm -rf "$FOLDER"/"$SUBFOLDER"
+    mv docs/"$SUBFOLDER"/ "$FOLDER"/"$SUBFOLDER"
+    # commit
+    git add --all "$FOLDER"/"$SUBFOLDER"
+fi
+
+git status
+git commit -m "Documentation for https://github.com/adam-fowler/mqtt-nio/tree/$REVISION_HASH"
+git push
+# return to branch
+git checkout $CURRENT_BRANCH
+
+if [ "$STASH_RESULT" != "No local changes to save" ]; then
+    git stash pop
+fi
+