Merge pull request #1055 from chkr1011/add-code-doc

Added client documentation.

Source/MQTTnet/Server/CheckSubscriptionsResult.cs

@@ -8,6 +8,14 @@ namespace MQTTnet.Server
 
         public bool IsSubscribed { get; set; }
 
+        /// <summary>
+        /// Gets or sets the quality of service level.
+        /// The Quality of Service (QoS) level is an agreement between the sender of a message and the receiver of a message that defines the guarantee of delivery for a specific message.
+        /// There are 3 QoS levels in MQTT:
+        /// - At most once  (0): Message gets delivered no time, once or multiple times.
+        /// - At least once (1): Message gets delivered at least once (one time or more often).
+        /// - Exactly once  (2): Message gets delivered exactly once (It's ensured that the message only comes once).
+        /// </summary>
         public MqttQualityOfServiceLevel QualityOfServiceLevel { get; set; }
     }
 }

Source/MQTTnet/Server/IMqttClientSession.cs

@@ -4,6 +4,10 @@ namespace MQTTnet.Server
 {
     public interface IMqttClientSession
     {
+        /// <summary>
+        /// Gets the client identifier.
+        /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues.
+        /// </summary>
         string ClientId { get; }
 
         Task StopAsync();

Source/MQTTnet/Server/IMqttServerOptions.cs

@@ -4,6 +4,10 @@ namespace MQTTnet.Server
 {
     public interface IMqttServerOptions
     {
+        /// <summary>
+        /// Gets the client identifier.
+        /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues.
+        /// </summary>
         string ClientId { get; set; }
 
         bool EnablePersistentSessions { get; }

Source/MQTTnet/Server/IMqttServerPersistedSession.cs

@@ -5,14 +5,26 @@ namespace MQTTnet.Server
 {
     public interface IMqttServerPersistedSession
     {
+        /// <summary>
+        /// Gets the client identifier.
+        /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues.
+        /// </summary>
         string ClientId { get; }
 
         IDictionary<object, object> Items { get; }
 
         IList<MqttTopicFilter> Subscriptions { get; }
 
+        /// <summary>
+        /// Gets the last will message.
+        /// In MQTT, you use the last will message feature to notify other clients about an ungracefully disconnected client.
+        /// </summary>
         MqttApplicationMessage WillMessage { get; }
 
+        /// <summary>
+        /// Gets the will delay interval.
+        /// This is the time between the client disconnect and the time the will message will be sent.
+        /// </summary>
         uint? WillDelayInterval { get; }
 
         DateTime? SessionExpiryTimestamp { get; }

Source/MQTTnet/Server/MqttApplicationMessageInterceptorContext.cs

@@ -18,6 +18,10 @@ namespace MQTTnet.Server
         /// </summary>
         public IMqttNetScopedLogger Logger { get; }
 
+        /// <summary>
+        /// Gets the client identifier.
+        /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues.
+        /// </summary>
         public string ClientId { get; }
 
         public MqttApplicationMessage ApplicationMessage { get; set; }

Source/MQTTnet/Server/MqttClientMessageQueueInterceptorContext.cs

@@ -20,6 +20,14 @@ namespace MQTTnet.Server
 
         public bool AcceptEnqueue { get; set; } = true;
 
+        /// <summary>
+        /// Gets or sets the supscription quality of service level.
+        /// The Quality of Service (QoS) level is an agreement between the sender of a message and the receiver of a message that defines the guarantee of delivery for a specific message.
+        /// There are 3 QoS levels in MQTT:
+        /// - At most once  (0): Message gets delivered no time, once or multiple times.
+        /// - At least once (1): Message gets delivered at least once (one time or more often).
+        /// - Exactly once  (2): Message gets delivered exactly once (It's ensured that the message only comes once).
+        /// </summary>
         public MqttQualityOfServiceLevel SubscriptionQualityOfServiceLevel { get; set; }
     }
 }

Source/MQTTnet/Server/MqttConnectionValidatorContext.cs

@@ -21,6 +21,10 @@ namespace MQTTnet.Server
             SessionItems = sessionItems;
         }
 
+        /// <summary>
+        /// Gets the client identifier.
+        /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues.
+        /// </summary>
         public string ClientId => _connectPacket.ClientId;
 
         public string Endpoint => _clientAdapter.Endpoint;
@@ -37,30 +41,88 @@ namespace MQTTnet.Server
 
         public string Password => Encoding.UTF8.GetString(RawPassword ?? new byte[0]);
 
+        /// <summary>
+        /// Gets or sets the will delay interval.
+        /// This is the time between the client disconnect and the time the will message will be sent.
+        /// </summary>
         public MqttApplicationMessage WillMessage => _connectPacket?.WillMessage;
 
+        /// <summary>
+        /// Gets or sets a value indicating whether clean sessions are used or not.
+        /// When a client connects to a broker it can connect using either a non persistent connection (clean session) or a persistent connection.
+        /// With a non persistent connection the broker doesn't store any subscription information or undelivered messages for the client.
+        /// This mode is ideal when the client only publishes messages.
+        /// It can also connect as a durable client using a persistent connection.
+        /// In this mode, the broker will store subscription information, and undelivered messages for the client.
+        /// </summary>
         public bool? CleanSession => _connectPacket?.CleanSession;
 
+        /// <summary>
+        /// Gets or sets the keep alive period.
+        /// The connection is normally left open by the client so that is can send and receive data at any time.
+        /// If no data flows over an open connection for a certain time period then the client will generate a PINGREQ and expect to receive a PINGRESP from the broker.
+        /// This message exchange confirms that the connection is open and working.
+        /// This period is known as the keep alive period. 
+        /// </summary>
         public ushort? KeepAlivePeriod => _connectPacket?.KeepAlivePeriod;
 
+        /// <summary>
+        /// Gets or sets the user properties.
+        /// In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to almost every type of MQTT packet.
+        /// As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add metadata to MQTT messages and pass information between publisher, broker, and subscriber.
+        /// The feature is very similar to the HTTP header concept.
+        /// Hint: MQTT 5 feature only.
+        /// </summary>
         public List<MqttUserProperty> UserProperties => _connectPacket?.Properties?.UserProperties;
 
+        /// <summary>
+        /// Gets or sets the authentication data.
+        /// Hint: MQTT 5 feature only.
+        /// </summary>
         public byte[] AuthenticationData => _connectPacket?.Properties?.AuthenticationData;
 
+        /// <summary>
+        /// Gets or sets the authentication method.
+        /// Hint: MQTT 5 feature only.
+        /// </summary>
         public string AuthenticationMethod => _connectPacket?.Properties?.AuthenticationMethod;
 
         public uint? MaximumPacketSize => _connectPacket?.Properties?.MaximumPacketSize;
 
+        /// <summary>
+        /// Gets or sets the receive maximum.
+        /// This gives the maximum length of the receive messages.
+        /// </summary>
         public ushort? ReceiveMaximum => _connectPacket?.Properties?.ReceiveMaximum;
 
+        /// <summary>
+        /// Gets or sets the topic alias maximum.
+        /// This gives the maximum length of the topic alias.
+        /// </summary>
         public ushort? TopicAliasMaximum => _connectPacket?.Properties?.TopicAliasMaximum;
 
+        /// <summary>
+        /// Gets the request problem information.
+        /// Hint: MQTT 5 feature only.
+        /// </summary>
         public bool? RequestProblemInformation => _connectPacket?.Properties?.RequestProblemInformation;
 
+        /// <summary>
+        /// Gets the request response information.
+        /// Hint: MQTT 5 feature only.
+        /// </summary>
         public bool? RequestResponseInformation => _connectPacket?.Properties?.RequestResponseInformation;
 
+        /// <summary>
+        /// Gets the session expiry interval.
+        /// The time after a session expires when it's not actively used.
+        /// </summary>
         public uint? SessionExpiryInterval => _connectPacket?.Properties?.SessionExpiryInterval;
 
+        /// <summary>
+        /// Gets or sets the will delay interval.
+        /// This is the time between the client disconnect and the time the will message will be sent.
+        /// </summary>
         public uint? WillDelayInterval => _connectPacket?.Properties?.WillDelayInterval;
 
         /// <summary>
@@ -79,14 +141,26 @@ namespace MQTTnet.Server
         }
 
         /// <summary>
-        /// This is used for MQTTv5 only. When a MQTTv3 client connects the enum value must be one which is
+        /// Gets or sets the reason code. When a MQTTv3 client connects the enum value must be one which is
         /// also supported in MQTTv3. Otherwise the connection attempt will fail because not all codes can be
         /// converted properly.
+        /// Hint: MQTT 5 feature only.
         /// </summary>
         public MqttConnectReasonCode ReasonCode { get; set; } = MqttConnectReasonCode.Success;
 
+        /// <summary>
+        /// Gets or sets the response user properties.
+        /// In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to almost every type of MQTT packet.
+        /// As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add metadata to MQTT messages and pass information between publisher, broker, and subscriber.
+        /// The feature is very similar to the HTTP header concept.
+        /// Hint: MQTT 5 feature only.
+        /// </summary>
         public List<MqttUserProperty> ResponseUserProperties { get; set; }
 
+        /// <summary>
+        /// Gets or sets the response authentication data.
+        /// Hint: MQTT 5 feature only.
+        /// </summary>
         public byte[] ResponseAuthenticationData { get; set; }
 
         public string AssignedClientIdentifier { get; set; }

Source/MQTTnet/Server/MqttQueuedApplicationMessage.cs

@@ -11,6 +11,14 @@ namespace MQTTnet.Server
 
         public bool IsRetainedMessage { get; set; }
 
+        /// <summary>
+        /// Gets or sets the subscription quality of service level.
+        /// The Quality of Service (QoS) level is an agreement between the sender of a message and the receiver of a message that defines the guarantee of delivery for a specific message.
+        /// There are 3 QoS levels in MQTT:
+        /// - At most once  (0): Message gets delivered no time, once or multiple times.
+        /// - At least once (1): Message gets delivered at least once (one time or more often).
+        /// - Exactly once  (2): Message gets delivered exactly once (It's ensured that the message only comes once).
+        /// </summary>
         public MqttQualityOfServiceLevel SubscriptionQualityOfServiceLevel { get; set; }
 
         [Obsolete("Use 'SubscriptionQualityOfServiceLevel' instead.")]

Source/MQTTnet/Server/MqttServerClientConnectedEventArgs.cs

@@ -9,6 +9,10 @@ namespace MQTTnet.Server
             ClientId = clientId ?? throw new ArgumentNullException(nameof(clientId));
         }
 
+        /// <summary>
+        /// Gets the client identifier.
+        /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues.
+        /// </summary>
         public string ClientId { get; }
     }
 }

Source/MQTTnet/Server/MqttServerClientDisconnectedEventArgs.cs

@@ -9,7 +9,11 @@ namespace MQTTnet.Server
             ClientId = clientId ?? throw new ArgumentNullException(nameof(clientId));
             DisconnectType = disconnectType;
         }
-        
+
+        /// <summary>
+        /// Gets the client identifier.
+        /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues.
+        /// </summary>
         public string ClientId { get; }
 
         public MqttClientDisconnectType DisconnectType { get; }

Source/MQTTnet/Server/MqttServerClientSubscribedTopicEventArgs.cs

@@ -10,8 +10,16 @@ namespace MQTTnet.Server
             TopicFilter = topicFilter ?? throw new ArgumentNullException(nameof(topicFilter));
         }
 
+        /// <summary>
+        /// Gets the client identifier.
+        /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues.
+        /// </summary>
         public string ClientId { get; }
 
+        /// <summary>
+        /// Gets the topic filter.
+        /// The topic filter can contain topics and wildcards.
+        /// </summary>
         public MqttTopicFilter TopicFilter { get; }
     }
 }

Source/MQTTnet/Server/MqttServerClientUnsubscribedTopicEventArgs.cs

@@ -10,8 +10,16 @@ namespace MQTTnet.Server
             TopicFilter = topicFilter ?? throw new ArgumentNullException(nameof(topicFilter));
         }
 
+        /// <summary>
+        /// Gets the client identifier.
+        /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues.
+        /// </summary>
         public string ClientId { get; }
 
+        /// <summary>
+        /// Gets or sets the topic filter.
+        /// The topic filter can contain topics and wildcards.
+        /// </summary>
         public string TopicFilter { get; }
     }
 }

Source/MQTTnet/Server/MqttServerOptions.cs

@@ -8,6 +8,10 @@ namespace MQTTnet.Server
 
         public MqttServerTlsTcpEndpointOptions TlsEndpointOptions { get; } = new MqttServerTlsTcpEndpointOptions();
 
+        /// <summary>
+        /// Gets or sets the client identifier.
+        /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues.
+        /// </summary>
         public string ClientId { get; set; }
 
         public bool EnablePersistentSessions { get; set; }

Source/MQTTnet/Server/MqttSubscriptionInterceptorContext.cs

@@ -11,8 +11,16 @@ namespace MQTTnet.Server
             SessionItems = sessionItems;
         }
 
+        /// <summary>
+        /// Gets the client identifier.
+        /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues.
+        /// </summary>
         public string ClientId { get; }
 
+        /// <summary>
+        /// Gets or sets the topic filter.
+        /// The topic filter can contain topics and wildcards.
+        /// </summary>
         public MqttTopicFilter TopicFilter { get; set; }
 
         /// <summary>

Source/MQTTnet/Server/MqttUnsubscriptionInterceptorContext.cs

@@ -11,8 +11,17 @@ namespace MQTTnet.Server
             SessionItems = sessionItems;
         }
 
+        /// <summary>
+        /// Gets the client identifier.
+        /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues.
+        /// </summary>
         public string ClientId { get; }
 
+        /// <summary>
+        /// Gets or sets the MQTT topic.
+        /// In MQTT, the word topic refers to an UTF-8 string that the broker uses to filter messages for each connected client.
+        /// The topic consists of one or more topic levels. Each topic level is separated by a forward slash (topic level separator). 
+        /// </summary>
         public string Topic { get; set; }
 
         /// <summary>

Source/MQTTnet/Server/Status/IMqttClientStatus.cs

@@ -6,6 +6,10 @@ namespace MQTTnet.Server.Status
 {
     public interface IMqttClientStatus
     {
+        /// <summary>
+        /// Gets the client identifier.
+        /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues.
+        /// </summary>
         string ClientId { get; }
 
         string Endpoint { get; }

Source/MQTTnet/Server/Status/IMqttSessionStatus.cs

@@ -5,6 +5,10 @@ namespace MQTTnet.Server.Status
 {
     public interface IMqttSessionStatus
     {
+        /// <summary>
+        /// Gets the client identifier.
+        /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues.
+        /// </summary>
         string ClientId { get; }
 
         long PendingApplicationMessagesCount { get; }

Source/MQTTnet/Server/Status/MqttClientStatus.cs

@@ -14,6 +14,10 @@ namespace MQTTnet.Server.Status
             _connection = connection ?? throw new ArgumentNullException(nameof(connection));
         }
 
+        /// <summary>
+        /// Gets or sets the client identifier.
+        /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues.
+        /// </summary>
         public string ClientId { get; set; }
 
         public string Endpoint { get; set; }

Source/MQTTnet/Server/Status/MqttSessionStatus.cs

@@ -15,6 +15,10 @@ namespace MQTTnet.Server.Status
             _sessionsManager = sessionsManager ?? throw new ArgumentNullException(nameof(sessionsManager));
         }
 
+        /// <summary>
+        /// Gets or sets the client identifier.
+        /// Hint: This identifier needs to be unique over all used clients / devices on the broker to avoid connection issues.
+        /// </summary>
         public string ClientId { get; set; }
 
         public long PendingApplicationMessagesCount { get; set; }