From 6d933679f373ba2f80edf708f21931f71de72a7d Mon Sep 17 00:00:00 2001
From: Brendan Forster <brendan@github.com>
Date: Sun, 14 Dec 2014 17:42:19 +0930
Subject: [PATCH] fleshing out some of IGitHubClient

---
 Octokit/GitHubClient.cs  | 120 +++++++++++++++++++++++++++++++++
 Octokit/IGitHubClient.cs | 141 ++++++++++++++++++++++++++++++++++-----
 2 files changed, 246 insertions(+), 15 deletions(-)

diff --git a/Octokit/GitHubClient.cs b/Octokit/GitHubClient.cs
index 4580642a..a1e5e67f 100644
--- a/Octokit/GitHubClient.cs
+++ b/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");
diff --git a/Octokit/IGitHubClient.cs b/Octokit/IGitHubClient.cs
index 48803046..a828c83e 100644
--- a/Octokit/IGitHubClient.cs
+++ b/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; }
     }
 }