diff --git a/Octokit.Reactive/Clients/IObservableIssueCommentsClient.cs b/Octokit.Reactive/Clients/IObservableIssueCommentsClient.cs
index 906a8814..b78e3c0b 100644
--- a/Octokit.Reactive/Clients/IObservableIssueCommentsClient.cs
+++ b/Octokit.Reactive/Clients/IObservableIssueCommentsClient.cs
@@ -4,6 +4,12 @@ using System.Reactive;
 
 namespace Octokit.Reactive
 {
+    /// <summary>
+    /// A client for GitHub's Issue Comments API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/issues/comments/">Issue Comments API documentation</a> for more information.
+    /// </remarks>
     public interface IObservableIssueCommentsClient
     {
         /// <summary>
diff --git a/Octokit.Reactive/Clients/ObservableIssueCommentsClient.cs b/Octokit.Reactive/Clients/ObservableIssueCommentsClient.cs
index f0011cf2..faa02218 100644
--- a/Octokit.Reactive/Clients/ObservableIssueCommentsClient.cs
+++ b/Octokit.Reactive/Clients/ObservableIssueCommentsClient.cs
@@ -5,6 +5,12 @@ using Octokit.Reactive.Internal;
 
 namespace Octokit.Reactive
 {
+    /// <summary>
+    /// A client for GitHub's Issue Comments API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/issues/comments/">Issue Comments API documentation</a> for more information.
+    /// </remarks>
     public class ObservableIssueCommentsClient : IObservableIssueCommentsClient
     {
         readonly IIssueCommentsClient _client;
diff --git a/Octokit/Clients/IIssueCommentsClient.cs b/Octokit/Clients/IIssueCommentsClient.cs
index 147c3b84..6cbd298e 100644
--- a/Octokit/Clients/IIssueCommentsClient.cs
+++ b/Octokit/Clients/IIssueCommentsClient.cs
@@ -19,7 +19,7 @@ namespace Octokit
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
         /// <param name="id">The issue comment id</param>
-        /// <returns></returns>
+        /// <returns>The <see cref="IssueComment"/>s for the specified Issue Comment.</returns>
         [SuppressMessage("Microsoft.Naming", "CA1716:IdentifiersShouldNotMatchKeywords", MessageId = "Get",
             Justification = "Method makes a network request")]
         Task<IssueComment> Get(string owner, string name, int id);
@@ -30,7 +30,7 @@ namespace Octokit
         /// <remarks>http://developer.github.com/v3/issues/comments/#list-comments-in-a-repository</remarks>
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
-        /// <returns></returns>
+        /// <returns>The list of <see cref="IssueComment"/>s for the specified Repository.</returns>
         Task<IReadOnlyList<IssueComment>> GetAllForRepository(string owner, string name);
 
         /// <summary>
@@ -40,7 +40,7 @@ namespace Octokit
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
         /// <param name="options">Options for changing the API response</param>
-        /// <returns></returns>
+        /// <returns>The list of <see cref="IssueComment"/>s for the specified Repository.</returns>
         Task<IReadOnlyList<IssueComment>> GetAllForRepository(string owner, string name, ApiOptions options);
 
         /// <summary>
@@ -50,7 +50,7 @@ namespace Octokit
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
         /// <param name="number">The issue number</param>
-        /// <returns></returns>
+        /// <returns>The list of <see cref="IssueComment"/>s for the specified Issue.</returns>
         Task<IReadOnlyList<IssueComment>> GetAllForIssue(string owner, string name, int number);
 
         /// <summary>
@@ -61,7 +61,7 @@ namespace Octokit
         /// <param name="name">The name of the repository</param>
         /// <param name="number">The issue number</param>
         /// <param name="options">Options for changing the API response</param>
-        /// <returns></returns>
+        /// <returns>The list of <see cref="IssueComment"/>s for the specified Issue.</returns>
         Task<IReadOnlyList<IssueComment>> GetAllForIssue(string owner, string name, int number, ApiOptions options);
 
         /// <summary>
@@ -72,7 +72,7 @@ namespace Octokit
         /// <param name="name">The name of the repository</param>
         /// <param name="number">The number of the issue</param>
         /// <param name="newComment">The new comment to add to the issue</param>
-        /// <returns></returns>
+        /// <returns>The <see cref="IssueComment"/> that was just created.</returns>
         Task<IssueComment> Create(string owner, string name, int number, string newComment);
 
         /// <summary>
@@ -83,7 +83,7 @@ namespace Octokit
         /// <param name="name">The name of the repository</param>
         /// <param name="id">The comment id</param>
         /// <param name="commentUpdate">The modified comment</param>
-        /// <returns></returns>
+        /// <returns>The <see cref="IssueComment"/> that was just updated.</returns>
         Task<IssueComment> Update(string owner, string name, int id, string commentUpdate);
 
         /// <summary>
diff --git a/Octokit/Clients/IssueCommentsClient.cs b/Octokit/Clients/IssueCommentsClient.cs
index 2bb32b32..303bc07e 100644
--- a/Octokit/Clients/IssueCommentsClient.cs
+++ b/Octokit/Clients/IssueCommentsClient.cs
@@ -26,7 +26,7 @@ namespace Octokit
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
         /// <param name="id">The issue comment id</param>
-        /// <returns></returns>
+        /// <returns>The <see cref="IssueComment"/>s for the specified Issue Comment.</returns>
         public Task<IssueComment> Get(string owner, string name, int id)
         {
             Ensure.ArgumentNotNullOrEmptyString(owner, "owner");
@@ -41,7 +41,7 @@ namespace Octokit
         /// <remarks>http://developer.github.com/v3/issues/comments/#list-comments-in-a-repository</remarks>
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
-        /// <returns></returns>
+        /// <returns>The list of <see cref="IssueComment"/>s for the specified Repository.</returns>
         public Task<IReadOnlyList<IssueComment>> GetAllForRepository(string owner, string name)
         {
             Ensure.ArgumentNotNullOrEmptyString(owner, "owner");
@@ -57,7 +57,7 @@ namespace Octokit
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
         /// <param name="options">Options for changing the API response</param>
-        /// <returns></returns>
+        /// <returns>The list of <see cref="IssueComment"/>s for the specified Repository.</returns>
         public Task<IReadOnlyList<IssueComment>> GetAllForRepository(string owner, string name, ApiOptions options)
         {
             Ensure.ArgumentNotNullOrEmptyString(owner, "owner");
@@ -74,7 +74,7 @@ namespace Octokit
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
         /// <param name="number">The issue number</param>
-        /// <returns></returns>
+        /// <returns>The list of <see cref="IssueComment"/>s for the specified Issue.</returns>
         public Task<IReadOnlyList<IssueComment>> GetAllForIssue(string owner, string name, int number)
         {
             Ensure.ArgumentNotNullOrEmptyString(owner, "owner");
@@ -90,7 +90,7 @@ namespace Octokit
         /// <param name="name">The name of the repository</param>
         /// <param name="number">The issue number</param>
         /// <param name="options">Options for changing the API response</param>
-        /// <returns></returns>
+        /// <returns>The list of <see cref="IssueComment"/>s for the specified Issue.</returns>
         public Task<IReadOnlyList<IssueComment>> GetAllForIssue(string owner, string name, int number, ApiOptions options)
         {
             Ensure.ArgumentNotNullOrEmptyString(owner, "owner");
@@ -108,7 +108,7 @@ namespace Octokit
         /// <param name="name">The name of the repository</param>
         /// <param name="number">The number of the issue</param>
         /// <param name="newComment">The new comment to add to the issue</param>
-        /// <returns></returns>
+        /// <returns>The <see cref="IssueComment"/> that was just created.</returns>
         public Task<IssueComment> Create(string owner, string name, int number, string newComment)
         {
             Ensure.ArgumentNotNullOrEmptyString(owner, "owner");
@@ -126,7 +126,7 @@ namespace Octokit
         /// <param name="name">The name of the repository</param>
         /// <param name="id">The comment id</param>
         /// <param name="commentUpdate">The modified comment</param>
-        /// <returns></returns>
+        /// <returns>The <see cref="IssueComment"/> that was just updated.</returns>
         public Task<IssueComment> Update(string owner, string name, int id, string commentUpdate)
         {
             Ensure.ArgumentNotNullOrEmptyString(owner, "owner");