fleshing out some of IGitHubClient

Octokit/GitHubClient.cs

@@ -8,6 +8,9 @@ namespace Octokit
     /// </summary>
     public class GitHubClient : IGitHubClient
     {
+        /// <summary>
+        /// The base address for the GitHub API
+        /// </summary>
         public static readonly Uri GitHubApiUrl = new Uri("https://api.github.com/");
         internal static readonly Uri GitHubDotComUrl = new Uri("https://github.com/");
 
@@ -131,22 +134,139 @@ namespace Octokit
         /// </summary>
         public IConnection Connection { get; private set; }
 
+        /// <summary>
+        /// Access GitHub's Authorization API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/oauth_authorizations/
+        /// </remarks>
         public IAuthorizationsClient Authorization { get; private set; }
+
+        /// <summary>
+        /// Access GitHub's Activity API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/activity/
+        /// </remarks>
         public IActivitiesClient Activity { get; private set; }
+
+        /// <summary>
+        /// Access GitHub's Issue API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/issues/
+        /// </remarks>
         public IIssuesClient Issue { get; private set; }
+
+        /// <summary>
+        /// Access GitHub's Miscellaneous API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/misc/
+        /// </remarks>
         public IMiscellaneousClient Miscellaneous { get; private set; }
+
+        /// <summary>
+        /// Access GitHub's OAuth API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/oauth/
+        /// </remarks>
         public IOauthClient Oauth { get; private set; }
+
+        /// <summary>
+        /// Access GitHub's Organizations API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/orgs/
+        /// </remarks>
         public IOrganizationsClient Organization { get; private set; }
+
+        /// <summary>
+        /// Access GitHub's Pull Requests API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/pulls/
+        /// </remarks>
         public IPullRequestsClient PullRequest { get; private set; }
+
+        /// <summary>
+        /// Access GitHub's Repositories API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/repos/
+        /// </remarks>
         public IRepositoriesClient Repository { get; private set; }
+
+        /// <summary>
+        /// Access GitHub's Gists API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/gists/
+        /// </remarks>
         public IGistsClient Gist { get; private set; }
+
+        // TODO: this should be under Repositories to align with the API docs
+        /// <summary>
+        /// Access GitHub's Releases API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/repos/releases/
+        /// </remarks>
         public IReleasesClient Release { get; private set; }
+
+        // TODO: this should be under Users to align with the API docs
+        // TODO: this should be named PublicKeys to align with the API docs
+        /// <summary>
+        /// Access GitHub's Public Keys API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/users/keys/
+        /// </remarks>
         public ISshKeysClient SshKey { get; private set; }
+
+        /// <summary>
+        /// Access GitHub's Users API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/users/
+        /// </remarks>
         public IUsersClient User { get; private set; }
+
+        // TODO: this should be under Activities to align with the API docs
+        /// <summary>
+        /// Access GitHub's Notifications API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/activity/notifications/
+        /// </remarks>
         public INotificationsClient Notification { get; private set; }
+
+        /// <summary>
+        /// Access GitHub's Git Data API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/git/
+        /// </remarks>
         public IGitDatabaseClient GitDatabase { get; private set; }
+
+        /// <summary>
+        /// Access GitHub's Search API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/search/
+        /// </remarks>
         public ISearchClient Search { get; private set; }
+
+        // TODO: this should be under Repositories to align with the API docs
+        /// <summary>
+        /// Access GitHub's Deployments API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/repos/deployments/
+        /// </remarks>
         public IDeploymentsClient Deployment { get; private set; }
+
         static Uri FixUpBaseUri(Uri uri)
         {
             Ensure.ArgumentNotNull(uri, "uri");

Octokit/IGitHubClient.cs

@@ -7,22 +7,133 @@ namespace Octokit
     /// </summary>
     public interface IGitHubClient
     {
+        /// <summary>
+        /// Provides a client connection to make rest requests to HTTP endpoints.
+        /// </summary>
         IConnection Connection { get; }
-        IAuthorizationsClient Authorization { get; }
-        IActivitiesClient Activity { get; }
-        IIssuesClient Issue { get; }
-        IMiscellaneousClient Miscellaneous { get; }
-        IOauthClient Oauth { get; }
-        IOrganizationsClient Organization { get; }
-        IPullRequestsClient PullRequest { get; }
-        IRepositoriesClient Repository { get; }
-        IGistsClient Gist { get; }
-        IReleasesClient Release { get; }
-        ISshKeysClient SshKey { get; }
-        IUsersClient User { get; }
-        INotificationsClient Notification { get; }
-        IGitDatabaseClient GitDatabase { get; }
-        ISearchClient Search { get; }
 
+        /// <summary>
+        /// Access GitHub's Authorization API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/oauth_authorizations/
+        /// </remarks>
+        IAuthorizationsClient Authorization { get; }
+
+        /// <summary>
+        /// Access GitHub's Activity API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/activity/
+        /// </remarks>
+        IActivitiesClient Activity { get; }
+
+        /// <summary>
+        /// Access GitHub's Issue API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/issues/
+        /// </remarks>
+        IIssuesClient Issue { get; }
+
+        /// <summary>
+        /// Access GitHub's Miscellaneous API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/misc/
+        /// </remarks>
+        IMiscellaneousClient Miscellaneous { get; }
+
+        /// <summary>
+        /// Access GitHub's OAuth API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/oauth/
+        /// </remarks>
+        IOauthClient Oauth { get; }
+
+        /// <summary>
+        /// Access GitHub's Organizations API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/orgs/
+        /// </remarks>
+        IOrganizationsClient Organization { get; }
+
+        /// <summary>
+        /// Access GitHub's Pull Requests API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/pulls/
+        /// </remarks>
+        IPullRequestsClient PullRequest { get; }
+
+        /// <summary>
+        /// Access GitHub's Repositories API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/repos/
+        /// </remarks>
+        IRepositoriesClient Repository { get; }
+
+        /// <summary>
+        /// Access GitHub's Gists API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/gists/
+        /// </remarks>
+        IGistsClient Gist { get; }
+
+        // TODO: this should be under Repositories to align with the API docs
+        /// <summary>
+        /// Access GitHub's Releases API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/repos/releases/
+        /// </remarks>
+        IReleasesClient Release { get; }
+
+        // TODO: this should be under Users to align with the API docs
+        // TODO: this should be named PublicKeys to align with the API docs
+        /// <summary>
+        /// Access GitHub's Public Keys API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/users/keys/
+        /// </remarks>
+        ISshKeysClient SshKey { get; }
+
+        /// <summary>
+        /// Access GitHub's Users API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/users/
+        /// </remarks>
+        IUsersClient User { get; }
+
+        // TODO: this should be under Activities to align with the API docs
+        /// <summary>
+        /// Access GitHub's Notifications API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/activity/notifications/
+        /// </remarks>
+        INotificationsClient Notification { get; }
+
+        /// <summary>
+        /// Access GitHub's Git Data API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/git/
+        /// </remarks>
+        IGitDatabaseClient GitDatabase { get; }
+
+        /// <summary>
+        /// Access GitHub's Search API.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the API docmentation for more information: https://developer.github.com/v3/search/
+        /// </remarks>
+        ISearchClient Search { get; }
     }
 }