API docs completed (#149)

* API docs completed

* review changes

Author: mhowlett

src/Confluent.Kafka/BrokerMetadata.cs

@@ -23,17 +23,46 @@ namespace Confluent.Kafka
     /// </summary>
     public class BrokerMetadata
     {
+        /// <summary>
+        ///     Initializes a new BrokerMetadata class instance.
+        /// </summary>
+        /// <param name="brokerId">
+        ///     The Kafka broker id.
+        /// </param>
+        /// <param name="host">
+        ///     The Kafka broker hostname.
+        /// </param>
+        /// <param name="port">
+        ///     The Kafka broker port.
+        /// </param>
         public BrokerMetadata(int brokerId, string host, int port)
         {
             BrokerId = brokerId;
             Host = host;
             Port = port;
         }
 
+        /// <summary>
+        ///     Gets the Kafka broker id.
+        /// </summary>
         public int BrokerId { get; }
+
+        /// <summary>
+        ///     Gets the Kafka broker hostname.
+        /// </summary>
         public string Host { get; }
+
+        /// <summary>
+        ///     Gets the Kafka broker port.
+        /// </summary>
         public int Port { get; }
 
+        /// <summary>
+        ///     Returns a JSON representation of the BrokerMetadata object.
+        /// </summary>
+        /// <returns>
+        ///     A JSON representation of the BrokerMetadata object.
+        /// </returns>
         public override string ToString()
             => $"{{ \"BrokerId\": {BrokerId}, \"Host\": \"{Host}\", \"Port\": {Port} }}";
     }

src/Confluent.Kafka/Error.cs

@@ -26,14 +26,14 @@ public class Error
     {
         /// <summary>
         ///     Initialize a new Error instance from a particular
-        ///     ErrorCode value.
+        ///     <see cref="ErrorCode"/> value.
         /// </summary>
         /// <param name="code">
-        ///     The ErrorCode value associated with this Error.
+        ///     The <see cref="ErrorCode"/> value associated with this Error.
         /// </param>
         /// <remarks>
         ///     The reason string associated with this Error will
-        ///     be a static value associated with the ErrorCode.
+        ///     be a static value associated with the <see cref="ErrorCode"/>.
         /// </remarks>
         public Error(ErrorCode code)
         {
@@ -43,11 +43,11 @@ public Error(ErrorCode code)
 
         /// <summary>
         ///     Initialize a new Error instance from a particular
-        ///     ErrorCode value and custom <paramref name="reason"/>
+        ///     <see cref="ErrorCode"/> value and custom <paramref name="reason"/>
         ///     string.
         /// </summary>
         /// <param name="code">
-        ///     The ErrorCode value associated with this Error.
+        ///     The <see cref="ErrorCode"/> value associated with this Error.
         /// </param>
         /// <param name="reason">
         ///     A custom reason string associated with the error
@@ -61,7 +61,7 @@ public Error(ErrorCode code, string reason)
         }
 
         /// <summary>
-        ///     Gets the ErrorCode associated with this Error.
+        ///     Gets the <see cref="ErrorCode"/> associated with this Error.
         /// </summary>
         public ErrorCode Code { get; }
 
@@ -93,15 +93,42 @@ public bool IsLocalError
         public bool IsBrokerError
             => (int)Code > 0;
 
+        /// <summary>
+        ///     Converts the specified Error value to a boolean value (false if e.Code == ErrorCode.NoError, true otherwise).
+        /// </summary>
+        /// <param name="e">
+        ///     The Error value to convert.
+        /// </param>
         public static implicit operator bool(Error e)
             => e.HasError;
 
+        /// <summary>
+        ///     Converts the specified Error value to the value of it's Code property.
+        /// </summary>
+        /// <param name="e">
+        ///     The Error value to convert.
+        /// </param>
         public static implicit operator ErrorCode(Error e)
             => e.Code;
 
+        /// <summary>
+        ///     Converts the specified <see cref="ErrorCode"/> value to it's corresponding rich Error value.
+        /// </summary>
+        /// <param name="c">
+        ///     The <see cref="ErrorCode"/> value to convert.
+        /// </param>
         public static implicit operator Error(ErrorCode c)
             => new Error(c);
 
+        /// <summary>
+        ///     Tests whether this Error instance is equal to the specified object.
+        /// </summary>
+        /// <param name="obj">
+        ///     The object to test.
+        /// </param>
+        /// <returns>
+        ///     true if obj is an Error and the Code property values are equal. false otherwise.
+        /// </returns>
         public override bool Equals(object obj)
         {
             if (!(obj is Error))
@@ -112,12 +139,42 @@ public override bool Equals(object obj)
             return ((Error)obj).Code == Code;
         }
 
+        /// <summary>
+        ///     Returns a hash code for this Error value.
+        /// </summary>
+        /// <returns>
+        ///     An integer that specifies a hash value for this Error value.
+        /// </returns>
         public override int GetHashCode()
             => Code.GetHashCode();
 
+        /// <summary>
+        ///     Tests whether Error value a is equal to Error value b.
+        /// </summary>
+        /// <param name="a">
+        ///     The first Error value to compare.
+        /// </param>
+        /// <param name="b">
+        ///     The second Error value to compare.
+        /// </param>
+        /// <returns>
+        ///     true if Error values a and b are equal. false otherwise.
+        /// </returns>
         public static bool operator ==(Error a, Error b)
             => a.Equals(b);
 
+        /// <summary>
+        ///     Tests whether Error value a is not equal to Error value b.
+        /// </summary>
+        /// <param name="a">
+        ///     The first Error value to compare.
+        /// </param>
+        /// <param name="b">
+        ///     The second Error value to compare.
+        /// </param>
+        /// <returns>
+        ///     true if Error values a and b are not equal. false otherwise.
+        /// </returns>
         public static bool operator !=(Error a, Error b)
             => !(a == b);
 
@@ -127,6 +184,9 @@ public override int GetHashCode()
         ///     contextual error message, or a simple static
         ///     string representation of the error Code.
         /// </summary>
+        /// <returns>
+        ///     A string representation of the Error object.
+        /// </returns>
         public override string ToString()
         {
             // If a rich error string is available return that, otherwise fall

src/Confluent.Kafka/GroupInfo.cs

@@ -27,10 +27,34 @@ namespace Confluent.Kafka
     /// </summary>
     public class GroupInfo
     {
-        public GroupInfo(BrokerMetadata broker, string grp, Error error, string state, string protocolType, string protocol, List<GroupMemberInfo> members)
+        /// <summary>
+        ///     Initializes a new instance of the GroupInfo class.
+        /// </summary>
+        /// <param name="broker">
+        ///     Originating broker info.
+        /// </param>
+        /// <param name="group">
+        ///     The group name.
+        /// </param>
+        /// <param name="error">
+        ///     A rich <see cref="Error"/> value associated with the information encapsulated by this class.
+        /// </param>
+        /// <param name="state">
+        ///     The group state.
+        /// </param>
+        /// <param name="protocolType">
+        ///     The group protocol type.
+        /// </param>
+        /// <param name="protocol">
+        ///     The group protocol.
+        /// </param>
+        /// <param name="members">
+        ///     The group members.
+        /// </param>
+        public GroupInfo(BrokerMetadata broker, string group, Error error, string state, string protocolType, string protocol, List<GroupMemberInfo> members)
         {
             Broker = broker;
-            Group = grp;
+            Group = group;
             Error = error;
             State = state;
             ProtocolType = protocolType;
@@ -39,37 +63,37 @@ public GroupInfo(BrokerMetadata broker, string grp, Error error, string state, s
         }
 
         /// <summary>
-        ///     Originating-broker info.
+        ///     Gets the originating-broker info.
         /// </summary>
         public BrokerMetadata Broker { get; }
 
         /// <summary>
-        ///     Group name
+        ///     Gets the group name
         /// </summary>
         public string Group { get; }
 
         /// <summary>
-        ///     Broker-originated error
+        ///     Gets a rich <see cref="Error"/> value associated with the information encapsulated by this class.
         /// </summary>
         public Error Error { get; }
 
         /// <summary>
-        ///     Group state
+        ///     Gets the group state
         /// </summary>
         public string State { get; }
 
         /// <summary>
-        ///     Group protocol type
+        ///     Gets the group protocol type
         /// </summary>
         public string ProtocolType { get; }
 
         /// <summary>
-        ///     Group protocol
+        ///     Gets the group protocol
         /// </summary>
         public string Protocol { get; }
 
         /// <summary>
-        ///     Group members
+        ///     Gets the group members
         /// </summary>
         public List<GroupMemberInfo> Members { get; }
     }

src/Confluent.Kafka/GroupMemberInfo.cs

@@ -24,6 +24,24 @@ namespace Confluent.Kafka
     /// </summary>
     public class GroupMemberInfo {
 
+        /// <summary>
+        ///     Initializes a new GroupMemberInfo class instance.
+        /// </summary>
+        /// <param name="memberId">
+        ///     The member id (generated by the broker).
+        /// </param>
+        /// <param name="clientId">
+        ///     The client's client.id.
+        /// </param>
+        /// <param name="clientHost">
+        ///     The client's hostname.
+        /// </param>
+        /// <param name="memberMetadata">
+        ///     Gets the member metadata (binary). The format of this data depends on the protocol type.
+        /// </param>
+        /// <param name="memberAssignment">
+        ///     Gets the member assignment (binary). The format of this data depends on the protocol type.
+        /// </param>
         public GroupMemberInfo(string memberId, string clientId, string clientHost, byte[] memberMetadata, byte[] memberAssignment)
         {
             MemberId = memberId;
@@ -34,17 +52,17 @@ public GroupMemberInfo(string memberId, string clientId, string clientHost, byte
         }
 
         /// <summary>
-        ///     Member id (generated by broker)
+        ///     Gets the member id (generated by broker).
         /// </summary>
         public string MemberId { get; }
 
         /// <summary>
-        ///     Client's \p client.id
+        ///     Gets the client's client.id.
         /// </summary>
         public string ClientId { get; }
 
         /// <summary>
-        ///     Client's hostname
+        ///     Gets the client's hostname.
         /// </summary>
         public string ClientHost { get; }
 
@@ -53,12 +71,12 @@ public GroupMemberInfo(string memberId, string clientId, string clientHost, byte
         //       we want? (probably I think)
 
         /// <summary>
-        ///     Member metadata (binary), format depends on \p protocol_type.
+        ///     Gets the member metadata (binary). The format of this data depends on the protocol type.
         /// </summary>
         public byte[] MemberMetadata { get; }
 
         /// <summary>
-        ///     Member assignment (binary), format depends on \p protocol_type.
+        ///     Gets the member assignment (binary). The format of this data depends on the protocol type.
         /// </summary>
         public byte[] MemberAssignment { get; }
     }

src/Confluent.Kafka/ISerializingProducer.cs

@@ -14,7 +14,6 @@
 //
 // Refer to LICENSE for more information.
 
-using System;
 using System.Threading.Tasks;
 using Confluent.Kafka.Serialization;
 
@@ -43,14 +42,44 @@ public interface ISerializingProducer<TKey, TValue>
         /// </summary>
         ISerializer<TValue> ValueSerializer { get; }
 
-        Task<Message<TKey, TValue>> ProduceAsync(string topic, TKey key, TValue val);
+        /// <summary>
+        ///     Refer to <see cref="Producer{TKey, TValue}.ProduceAsync(string, TKey, TValue)"/>.
+        /// </summary>
+        Task<Message<TKey, TValue>> ProduceAsync(string topic, TKey key, TValue val);
+
+        /// <summary>
+        ///     Refer to <see cref="Producer{TKey, TValue}.ProduceAsync(string, TKey, TValue, int, bool)"/>.
+        /// </summary>
         Task<Message<TKey, TValue>> ProduceAsync(string topic, TKey key, TValue val, int partition, bool blockIfQueueFull);
+
+        /// <summary>
+        ///     Refer to <see cref="Producer{TKey, TValue}.ProduceAsync(string, TKey, TValue, int)"/>.
+        /// </summary>
         Task<Message<TKey, TValue>> ProduceAsync(string topic, TKey key, TValue val, int partition);
+
+        /// <summary>
+        ///     Refer to <see cref="Producer{TKey, TValue}.ProduceAsync(string, TKey, TValue, bool)"/>.
+        /// </summary>
         Task<Message<TKey, TValue>> ProduceAsync(string topic, TKey key, TValue val, bool blockIfQueueFull);
 
+        /// <summary>
+        ///     Refer to <see cref="Producer{TKey, TValue}.ProduceAsync(string, TKey, TValue, IDeliveryHandler{TKey, TValue})"/>.
+        /// </summary>
         void ProduceAsync(string topic, TKey key, TValue val, IDeliveryHandler<TKey, TValue> deliveryHandler);
+
+        /// <summary>
+        ///     Refer to <see cref="Producer{TKey, TValue}.ProduceAsync(string, TKey, TValue, int, bool, IDeliveryHandler{TKey, TValue})"/>.
+        /// </summary>
         void ProduceAsync(string topic, TKey key, TValue val, int partition, bool blockIfQueueFull, IDeliveryHandler<TKey, TValue> deliveryHandler);
+
+        /// <summary>
+        ///     Refer to <see cref="Producer{TKey, TValue}.ProduceAsync(string, TKey, TValue, int, IDeliveryHandler{TKey, TValue})"/>.
+        /// </summary>
         void ProduceAsync(string topic, TKey key, TValue val, int partition, IDeliveryHandler<TKey, TValue> deliveryHandler);
+
+        /// <summary>
+        ///     Refer to <see cref="Producer{TKey, TValue}.ProduceAsync(string, TKey, TValue, bool, IDeliveryHandler{TKey, TValue})"/>.
+        /// </summary>
         void ProduceAsync(string topic, TKey key, TValue val, bool blockIfQueueFull, IDeliveryHandler<TKey, TValue> deliveryHandler);
     }
 }