Merge pull request #253 from pmacn/feature/documentation

Documentation

Octokit/Clients/ActivitiesClient.cs

@@ -2,6 +2,10 @@
 {
     public class ActivitiesClient : ApiClient, IActivitiesClient
     {
+        /// <summary>
+        /// Instantiate a new GitHub Activities API client.
+        /// </summary>
+        /// <param name="apiConnection">An API connection</param>
         public ActivitiesClient(IApiConnection apiConnection)
             : base(apiConnection)
         {

Octokit/Clients/AssigneesClient.cs

@@ -6,6 +6,10 @@ namespace Octokit
 {
     public class AssigneesClient : ApiClient, IAssigneesClient
     {
+        /// <summary>
+        /// Instantiates a new GitHub Issue Assignees API client.
+        /// </summary>
+        /// <param name="apiConnection">An API connection</param>
         public AssigneesClient(IApiConnection apiConnection) : base(apiConnection)
         {
         }

Octokit/Clients/BlobsClient.cs

@@ -4,6 +4,10 @@ namespace Octokit
 {
     public class BlobsClient : ApiClient, IBlobsClient
     {
+        /// <summary>
+        /// Instantiates a new GitHub Git Blobs API client.
+        /// </summary>
+        /// <param name="apiConnection">An API connection</param>
         public BlobsClient(IApiConnection apiConnection)
             : base(apiConnection)
         {

Octokit/Clients/CommitsClient.cs

@@ -4,6 +4,10 @@ namespace Octokit
 {
     public class CommitsClient : ApiClient, ICommitsClient
     {
+        /// <summary>
+        /// Instantiates a new GitHub Git Commits API client.
+        /// </summary>
+        /// <param name="apiConnection">An API connection</param>
         public CommitsClient(IApiConnection apiConnection) : 
             base(apiConnection)
         {

Octokit/Clients/EventsClient.cs

@@ -5,6 +5,10 @@ namespace Octokit
 {
     public class EventsClient : ApiClient, IEventsClient
     {
+        /// <summary>
+        /// Instantiates a new GitHub Issue Events API client.
+        /// </summary>
+        /// <param name="apiConnection">An API connection</param>
         public EventsClient(IApiConnection apiConnection)
             : base(apiConnection)
         {

Octokit/Clients/GistCommentsClient.cs

@@ -5,6 +5,10 @@ namespace Octokit
 {
     public class GistCommentsClient : ApiClient, IGistCommentsClient
     {
+        /// <summary>
+        /// Instantiates a new GitHub Gist Comments API client.
+        /// </summary>
+        /// <param name="apiConnection">An API connection</param>
         public GistCommentsClient(IApiConnection apiConnection) : base(apiConnection)
         {
         }

Octokit/Clients/GistsClient.cs

@@ -4,6 +4,10 @@ namespace Octokit
 {
     public class GistsClient : ApiClient, IGistsClient
     {
+        /// <summary>
+        /// Instantiates a new GitHub Gists API client.
+        /// </summary>
+        /// <param name="apiConnection">An API connection</param>
         public GistsClient(IApiConnection apiConnection) : 
             base(apiConnection)
         {

Octokit/Clients/GitDatabaseClient.cs

@@ -2,6 +2,10 @@
 {
     public class GitDatabaseClient : ApiClient, IGitDatabaseClient
     {
+        /// <summary>
+        /// Instantiates a new GitHub Git API client.
+        /// </summary>
+        /// <param name="apiConnection">An API connection</param>
         public GitDatabaseClient(IApiConnection apiConnection) 
             : base(apiConnection)
         {

Octokit/Clients/IActivitiesClient.cs

@@ -1,5 +1,11 @@
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's Activity API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/activity/">Activity API documentation</a> for more information.
+    /// </remarks>
     public interface IActivitiesClient
     {
         IEventsClient Events { get; }

Octokit/Clients/IAssigneesClient.cs

@@ -3,6 +3,12 @@ using System.Threading.Tasks;
 
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's Issue Assignees API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/issues/assignees/">Issue Assignees API documentation</a> for more information.
+    /// </remarks>
     public interface IAssigneesClient
     {
         /// <summary>

Octokit/Clients/IBlobsClient.cs

@@ -2,6 +2,12 @@
 
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's Git Blobs API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/git/blobs/">Git Blobs API documentation</a> for more information.
+    /// </remarks>
     public interface IBlobsClient
     {
         /// <summary>

Octokit/Clients/ICommitStatusClient.cs

@@ -3,6 +3,12 @@ using System.Threading.Tasks;
 
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's Git Repository Status API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/repos/statuses/">Repository Statuses API documentation</a> for more information.
+    /// </remarks>
     public interface ICommitStatusClient
     {
         /// <summary>

Octokit/Clients/ICommitsClient.cs

@@ -3,6 +3,12 @@ using System.Threading.Tasks;
 
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's Git Commits API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/git/commits/">Git Commits API documentation</a> for more information.
+    /// </remarks>
     public interface ICommitsClient
     {
         /// <summary>

Octokit/Clients/IEventsClient.cs

@@ -3,6 +3,12 @@ using System.Threading.Tasks;
 
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's Activity Events API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/activity/events/">Activity Events API documentation</a> for more information
+    /// </remarks>
     public interface IEventsClient
     {
         /// <summary>

Octokit/Clients/IGistCommentsClient.cs

@@ -4,6 +4,12 @@ using System.Threading.Tasks;
 
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's Gist Comments API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/gists/comments/">Gist Comments API documentation</a> for more information.
+    /// </remarks>
     public interface IGistCommentsClient
     {
         /// <summary>

Octokit/Clients/IGistsClient.cs

@@ -3,6 +3,12 @@ using System.Threading.Tasks;
 
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's Gists API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/gists/">Gists API documentation</a> for more information.
+    /// </remarks>
     public interface IGistsClient
     {
         IGistCommentsClient Comment { get; set; }

Octokit/Clients/IGitDatabaseClient.cs

@@ -1,8 +1,11 @@
 namespace Octokit
 {
     /// <summary>
-    /// Used to maintain api structure therefore contains no methods
+    /// A client for GitHub's Git Database API. Gives you access to read and write raw Git objects and to list and update your references.
     /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/git/">Git API documentation</a> for more information.
+    /// </remarks>
     public interface IGitDatabaseClient
     {
         IBlobsClient Blob { get; set; }

Octokit/Clients/IIssueCommentsClient.cs

@@ -4,6 +4,12 @@ using System.Threading.Tasks;
 
 namespace Octokit
 {
+    /// <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 IIssueCommentsClient
     {
         /// <summary>

Octokit/Clients/IIssuesClient.cs

@@ -4,6 +4,12 @@ using System.Threading.Tasks;
 
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's Issues API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/issues/">Issues API documentation</a> for more information.
+    /// </remarks>
     public interface IIssuesClient
     {
         IAssigneesClient Assignee { get; }

Octokit/Clients/IIssuesEventsClient.cs

@@ -4,6 +4,12 @@ using System.Threading.Tasks;
 
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's Issue Events API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/issues/events/">Issue Events API documentation</a> for more information.
+    /// </remarks>
     public interface IIssuesEventsClient
     {
         /// <summary>

Octokit/Clients/IMilestonesClient.cs

@@ -4,6 +4,12 @@ using System.Threading.Tasks;
 
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's Issue Milestones API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/issues/milestones/">Issue Milestones API documentation</a> for more information.
+    /// </remarks>
     public interface IMilestonesClient
     {
         /// <summary>

Octokit/Clients/IMiscellaneousClient.cs

@@ -11,7 +11,7 @@ namespace Octokit
     /// A client for GitHub's miscellaneous APIs.
     /// </summary>
     /// <remarks>
-    /// See the <a href="http://developer.github.com/v3/misc/">miscellaneous API documentation</a> for more details.
+    /// See the <a href="http://developer.github.com/v3/misc/">Miscellaneous API documentation</a> for more details.
     /// </remarks>
     public interface IMiscellaneousClient
     {

Octokit/Clients/INotificationsClient.cs

@@ -4,6 +4,12 @@ using System.Threading.Tasks;
 
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's Activity Notifications API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/activity/notifications/">Activity Notifications API documentation</a> for more information.
+    /// </remarks>
     public interface INotificationsClient
     {
         /// <summary>

Octokit/Clients/IOrganizationMembersClient.cs

@@ -3,6 +3,12 @@ using System.Threading.Tasks;
 
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's Organization Members API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/orgs/members/">Orgs API documentation</a> for more information.
+    /// </remarks>
     public interface IOrganizationMembersClient
     {
         /// <summary>

Octokit/Clients/IReferencesClient.cs

@@ -4,6 +4,12 @@ using System.Threading.Tasks;
 
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's References API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/git/refs/">References API documentation</a> for more information.
+    /// </remarks>
     public interface IReferencesClient
     {
         /// <summary>

Octokit/Clients/ISshKeysClient.cs

@@ -4,6 +4,12 @@ using System.Threading.Tasks;
 
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's User Keys API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/users/keys/">Users API documentation</a> for more information.
+    /// </remarks>
     public interface ISshKeysClient
     {
         /// <summary>

Octokit/Clients/IStarredClient.cs

@@ -3,6 +3,12 @@ using System.Threading.Tasks;
 
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's Activity Starring API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/activity/starring/">Activity Starring API documentation</a> for more information.
+    /// </remarks>
     public interface IStarredClient
     {
         /// <summary>

Octokit/Clients/ITagsClient.cs

@@ -3,6 +3,12 @@ using System.Threading.Tasks;
 
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's Git Tags API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/git/tags/">Git Tags API documentation</a> for more information.
+    /// </remarks>
     public interface ITagsClient
     {
         /// <summary>

Octokit/Clients/ITeamsClient.cs

@@ -7,10 +7,10 @@ using System.Threading.Tasks;
 namespace Octokit
 {
     /// <summary>
-    /// A client for GitHub's Org Teams API.
+    /// A client for GitHub's Organization Teams API.
     /// </summary>
     /// <remarks>
-    /// See the <a href="http://developer.github.com/v3/orgs/teams/">Orgs API documentation</a> for more information.
+    /// See the <a href="http://developer.github.com/v3/orgs/teams/">Organization Teams API documentation</a> for more information.
     /// </remarks>
     public interface ITeamsClient
     {

Octokit/Clients/ITreesClient.cs

@@ -2,6 +2,12 @@
 
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's Git Trees API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/git/trees/">Git Trees API documentation</a> for more information.
+    /// </remarks>
     public interface ITreesClient
     {
         /// <summary>

Octokit/Clients/IUsersClient.cs

@@ -4,6 +4,12 @@ using System.Threading.Tasks;
 
 namespace Octokit
 {
+    /// <summary>
+    /// A client for GitHub's Users API.
+    /// </summary>
+    /// <remarks>
+    /// See the <a href="http://developer.github.com/v3/users/">Users API documentation</a> for more information.
+    /// </remarks>
     public interface IUsersClient
     {
         /// <summary>

Octokit/Clients/IssueCommentsClient.cs

@@ -6,6 +6,10 @@ namespace Octokit
 {
     public class IssueCommentsClient : ApiClient, IIssueCommentsClient
     {
+        /// <summary>
+        /// Instantiates a new GitHub Issue Comments API client.
+        /// </summary>
+        /// <param name="apiConnection">An API connection</param>
         public IssueCommentsClient(IApiConnection apiConnection) : base(apiConnection)
         {
         }

Octokit/Clients/IssuesClient.cs

@@ -5,6 +5,10 @@ namespace Octokit
 {
     public class IssuesClient : ApiClient, IIssuesClient
     {
+        /// <summary>
+        /// Instantiates a new GitHub Issues API client.
+        /// </summary>
+        /// <param name="apiConnection">An API connection</param>
         public IssuesClient(IApiConnection apiConnection) : base(apiConnection)
         {
             Assignee = new AssigneesClient(apiConnection);

Octokit/Clients/MilestonesClient.cs

@@ -5,6 +5,10 @@ namespace Octokit
 {
     public class MilestonesClient : ApiClient, IMilestonesClient
     {
+        /// <summary>
+        /// Instantiates a new GitHub Issue Milestones API client.
+        /// </summary>
+        /// <param name="apiConnection">An API connection</param>
         public MilestonesClient(IApiConnection apiConnection) : base(apiConnection)
         {
         }

Octokit/Clients/NotificationsClient.cs

@@ -6,6 +6,10 @@ namespace Octokit
 {
     public class NotificationsClient : ApiClient, INotificationsClient
     {
+        /// <summary>
+        /// Instantiates a new GitHub Activity Notifications API client.
+        /// </summary>
+        /// <param name="apiConnection">An API connection</param>
         public NotificationsClient(IApiConnection apiConnection) : base(apiConnection)
         {
         }

Octokit/Clients/ReferencesClient.cs

@@ -5,6 +5,10 @@ namespace Octokit
 {
     public class ReferencesClient : ApiClient, IReferencesClient
     {
+        /// <summary>
+        /// Instantiates a new GitHub References API client
+        /// </summary>
+        /// <param name="apiConnection">An API connection</param>
         public ReferencesClient(IApiConnection apiConnection) : 
             base(apiConnection)
         {

Octokit/Clients/StarredClient.cs

@@ -7,6 +7,10 @@ namespace Octokit
 {
     public class StarredClient : ApiClient, IStarredClient
     {
+        /// <summary>
+        /// Instantiates a new GitHub Activity Starring API client.
+        /// </summary>
+        /// <param name="apiConnection">An API connection</param>
         public StarredClient(IApiConnection apiConnection) : base(apiConnection)
         {
         }

Octokit/Clients/TagsClient.cs

@@ -4,6 +4,10 @@ namespace Octokit
 {
     public class TagsClient : ApiClient, ITagsClient
     {
+        /// <summary>
+        /// Instantiates a new GitHub Git Tags API client.
+        /// </summary>
+        /// <param name="apiConnection">An API connection</param>
         public TagsClient(IApiConnection apiConnection) 
             : base(apiConnection)
         {

Octokit/Clients/TreesClient.cs

@@ -6,6 +6,10 @@ namespace Octokit
 {
     public class TreesClient : ApiClient, ITreesClient
     {
+        /// <summary>
+        /// Instantiates a new GitHub Git Trees API client.
+        /// </summary>
+        /// <param name="apiConnection">An API connection</param>
         public TreesClient(IApiConnection apiConnection)
             : base(apiConnection)
         {

Octokit/Clients/UsersClient.cs

@@ -15,6 +15,10 @@ namespace Octokit
     {
         static readonly Uri _userEndpoint = new Uri("user", UriKind.Relative);
 
+        /// <summary>
+        /// Instantiates a new GitHub Users API client.
+        /// </summary>
+        /// <param name="apiConnection">An API connection</param>
         public UsersClient(IApiConnection apiConnection) : base(apiConnection)
         {
         }

Octokit/Http/IConnection.cs

@@ -5,23 +5,100 @@ using System.Threading.Tasks;
 
 namespace Octokit
 {
+    /// <summary>
+    /// A connection for making HTTP requests against URI endpoints.
+    /// </summary>
     public interface IConnection
     {
+        /// <summary>
+        /// Performs an asynchronous HTTP GET request that expects a <seealso cref="IResponse"/> containing HTML.
+        /// </summary>
+        /// <param name="uri">URI endpoint to send request to</param>
+        /// <param name="parameters">Querystring parameters for the request</param>
+        /// <returns><seealso cref="IResponse"/> representing the received HTTP response</returns>
         Task<IResponse<string>> GetHtml(Uri uri, IDictionary<string, string> parameters);
+
+        /// <summary>
+        /// Performs an asynchronous HTTP GET request.
+        /// Attempts to map the response to an object of type <typeparamref name="T"/>
+        /// </summary>
+        /// <typeparam name="T">The type to map the response to</typeparam>
+        /// <param name="uri">URI endpoint to send request to</param>
+        /// <param name="parameters">Querystring parameters for the request</param>
+        /// <param name="accepts">Specifies accepted response media types.</param>
+        /// <returns><seealso cref="IResponse"/> representing the received HTTP response</returns>
         Task<IResponse<T>> GetAsync<T>(Uri uri, IDictionary<string, string> parameters, string accepts);
+
+        /// <summary>
+        /// Performs an asynchronous HTTP PATCH request.
+        /// Attempts to map the response body to an object of type <typeparamref name="T"/>
+        /// </summary>
+        /// <typeparam name="T">The type to map the response to</typeparam>
+        /// <param name="uri">URI endpoint to send request to</param>
+        /// <param name="body">The object to serialize as the body of the request</param>
+        /// <returns><seealso cref="IResponse"/> representing the received HTTP response</returns>
         Task<IResponse<T>> PatchAsync<T>(Uri uri, object body);
+
+        /// <summary>
+        /// Performs an asynchronous HTTP POST request.
+        /// Attempts to map the response body to an object of type <typeparamref name="T"/>
+        /// </summary>
+        /// <typeparam name="T">The type to map the response to</typeparam>
+        /// <param name="uri">URI endpoint to send request to</param>
+        /// <param name="body">The object to serialize as the body of the request</param>
+        /// <param name="accepts">Specifies accepted response media types.</param>
+        /// <param name="contentType">Specifies the media type of the request body</param>
+        /// <returns><seealso cref="IResponse"/> representing the received HTTP response</returns>
         Task<IResponse<T>> PostAsync<T>(Uri uri, object body, string accepts, string contentType);
+
+        /// <summary>
+        /// Performs an asynchronous HTTP PUT request.
+        /// Attempts to map the response body to an object of type <typeparamref name="T"/>
+        /// </summary>
+        /// <typeparam name="T">The type to map the response to</typeparam>
+        /// <param name="uri">URI endpoint to send request to</param>
+        /// <param name="body">The body of the request</param>
+        /// <returns><seealso cref="IResponse"/> representing the received HTTP response</returns>
         Task<IResponse<T>> PutAsync<T>(Uri uri, object body);
+
+        /// <summary>
+        /// Performs an asynchronous HTTP PUT request using the provided two factor authentication code.
+        /// Attempts to map the response body to an object of type <typeparamref name="T"/>
+        /// </summary>
+        /// <typeparam name="T">The type to map the response to</typeparam>
+        /// <param name="uri">URI endpoint to send request to</param>
+        /// <param name="body">The object to serialize as the body of the request</param>
+        /// <param name="twoFactorAuthenticationCode">Two factory authentication code to use</param>
+        /// <returns><seealso cref="IResponse"/> representing the received HTTP response</returns>
         Task<IResponse<T>> PutAsync<T>(Uri uri, object body, string twoFactorAuthenticationCode);
-        
+
+        /// <summary>
+        /// Performs an asynchronous HTTP PUT request that expects an empty response.
+        /// </summary>
+        /// <param name="uri">URI endpoint to send request to</param>
+        /// <returns>The returned <seealso cref="HttpStatusCode"/></returns>
         Task<HttpStatusCode> PutAsync(Uri uri);
 
+        /// <summary>
+        /// Performs an asynchronous HTTP DELETE request that expects an empty response.
+        /// </summary>
+        /// <param name="uri">URI endpoint to send request to</param>
+        /// <returns>The returned <seealso cref="HttpStatusCode"/></returns>
         Task<HttpStatusCode> DeleteAsync(Uri uri);
 
+        /// <summary>
+        /// Base address for the connection.
+        /// </summary>
         Uri BaseAddress { get; }
 
+        /// <summary>
+        /// Gets the <seealso cref="ICredentialStore"/> used to provide credentials for the connection.
+        /// </summary>
         ICredentialStore CredentialStore { get; }
 
+        /// <summary>
+        /// Gets or sets the credentials used by the connection.
+        /// </summary>
         Credentials Credentials { get; set; }
     }
 }