Address code review changes and add XML comments

Octokit.Reactive/Clients/ObservableAuthorizationsClient.cs

@@ -16,36 +16,60 @@ namespace Octokit.Reactive.Clients
             _client = client;
         }
 
+        /// <summary>
+        /// Get all <see cref="Authorization"/>s for the authenticated user. This method requires basic auth.
+        /// </summary>
+        /// <remarks>
+        /// See <a href="http://developer.github.com/v3/oauth/#list-your-authorizations">API documentation</a> for more
+        /// details.
+        /// </remarks>
+        /// <returns>An <see cref="Authorization"/></returns>
         public IObservable<IReadOnlyList<Authorization>> GetAll()
         {
             return _client.GetAll().ToObservable();
         }
 
+        /// <summary>
+        /// Get a specific <see cref="Authorization"/> for the authenticated user. This method requires basic auth.
+        /// </summary>
+        /// <remarks>
+        /// See <a href="http://developer.github.com/v3/oauth/#get-a-single-authorization">API documentation</a> for
+        /// more details.
+        /// </remarks>
+        /// <param name="id">The id of the <see cref="Authorization"/></param>
+        /// <returns>An <see cref="Authorization"/></returns>
         public IObservable<Authorization> Get(int id)
         {
             return _client.Get(id).ToObservable();
         }
+
         /// <summary>
         /// This method will create a new authorization for the specified OAuth application, only if an authorization 
         /// for that application doesn’t already exist for the user. It returns the user’s token for the application
         /// if one exists. Otherwise, it creates one.
         /// </summary>
-        /// <param name="clientId">Client ID for the OAuth application that is requesting the token.</param>
+        /// <remarks>
+        /// See <a href="http://developer.github.com/v3/oauth/#get-or-create-an-authorization-for-a-specific-app">API
+        /// documentation</a> for more details.
+        /// </remarks>
+        /// <param name="clientId">Client ID for the OAuth application that is requesting the token</param>
         /// <param name="clientSecret">The client secret</param>
-        /// <param name="authorization">Definse the scopes and metadata for the token</param>
+        /// <param name="newAuthorization">Defines the scopes and metadata for the token</param>
         /// <exception cref="AuthorizationException">Thrown when the user does not have permission to make 
         /// this request. Check </exception>
+        /// <exception cref="TwoFactorRequiredException">Thrown when the current account has two-factor
+        /// authentication enabled.</exception>
         /// <returns></returns>
         public IObservable<Authorization> GetOrCreateApplicationAuthentication(
             string clientId,
             string clientSecret,
-            AuthorizationUpdate authorization)
+            NewAuthorization newAuthorization)
         {
             Ensure.ArgumentNotNullOrEmptyString(clientId, "clientId");
             Ensure.ArgumentNotNullOrEmptyString(clientSecret, "clientSecret");
-            Ensure.ArgumentNotNull(authorization, "authorization");
+            Ensure.ArgumentNotNull(newAuthorization, "authorization");
 
-            return _client.GetOrCreateApplicationAuthentication(clientId, clientSecret, authorization)
+            return _client.GetOrCreateApplicationAuthentication(clientId, clientSecret, newAuthorization)
                 .ToObservable();
         }
 
@@ -54,45 +78,68 @@ namespace Octokit.Reactive.Clients
         /// for that application doesn’t already exist for the user. It returns the user’s token for the application
         /// if one exists. Otherwise, it creates one.
         /// </summary>
-        /// <param name="clientId">Client ID for the OAuth application that is requesting the token.</param>
+        /// <remarks>
+        /// See <a href="http://developer.github.com/v3/oauth/#get-or-create-an-authorization-for-a-specific-app">API 
+        /// documentation</a> for more details.
+        /// </remarks>
+        /// <param name="clientId">Client ID for the OAuth application that is requesting the token</param>
         /// <param name="clientSecret">The client secret</param>
-        /// <param name="authorization">Defines the scopes and metadata for the token</param>
+        /// <param name="newAuthorization">Defines the scopes and metadata for the token</param>
         /// <param name="twoFactorAuthenticationCode"></param>
         /// <exception cref="AuthorizationException">Thrown when the user does not have permission to make 
         /// this request. Check </exception>
         /// <exception cref="TwoFactorChallengeFailedException">Thrown when the two-factor code is not
         /// valid.</exception>
         /// <returns></returns>
-
         public IObservable<Authorization> GetOrCreateApplicationAuthentication(
             string clientId,
             string clientSecret,
-            AuthorizationUpdate authorization,
+            NewAuthorization newAuthorization,
             string twoFactorAuthenticationCode)
         {
             Ensure.ArgumentNotNullOrEmptyString(clientId, "clientId");
             Ensure.ArgumentNotNullOrEmptyString(clientSecret, "clientSecret");
-            Ensure.ArgumentNotNull(authorization, "authorization");
+            Ensure.ArgumentNotNull(newAuthorization, "authorization");
             Ensure.ArgumentNotNullOrEmptyString(twoFactorAuthenticationCode, "twoFactorAuthenticationCode");
 
-            return _client.GetOrCreateApplicationAuthentication(clientId, clientSecret, authorization, twoFactorAuthenticationCode)
+            return _client.GetOrCreateApplicationAuthentication(
+                clientId,
+                clientSecret,
+                newAuthorization,
+                twoFactorAuthenticationCode)
                 .ToObservable();
         }
 
-        public IObservable<Authorization> Update(int id, AuthorizationUpdate authorization)
+        /// <summary>
+        /// Create a new <see cref="Authorization"/>.
+        /// </summary>
+        /// <param name="newAuthorization">Information about the new authorization to create</param>
+        /// <returns></returns>
+        public IObservable<Authorization> Create(NewAuthorization newAuthorization)
         {
-            Ensure.ArgumentNotNull(authorization, "authorization");
+            Ensure.ArgumentNotNull(newAuthorization, "authorization");
 
-            return _client.Update(id, authorization).ToObservable();
+            return _client.Create(newAuthorization).ToObservable();
         }
 
-        public IObservable<Authorization> Create(AuthorizationUpdate authorization)
+        /// <summary>
+        /// Update the <see cref="Authorization"/> specified by the id.
+        /// </summary>
+        /// <param name="id">The id of the <see cref="Authorization"/></param>
+        /// <param name="authorizationUpdate">The changes to make to the authorization</param>
+        /// <returns></returns>
+        public IObservable<Authorization> Update(int id, AuthorizationUpdate authorizationUpdate)
         {
-            Ensure.ArgumentNotNull(authorization, "authorization");
+            Ensure.ArgumentNotNull(authorizationUpdate, "authorizationUpdate");
 
-            return _client.Create(authorization).ToObservable();
+            return _client.Update(id, authorizationUpdate).ToObservable();
         }
 
+        /// <summary>
+        /// Deletes an <see cref="Authorization"/>.
+        /// </summary>
+        /// <param name="id">The systemwide id of the authorization</param>
+        /// <returns></returns>
         public IObservable<Unit> Delete(int id)
         {
             return _client.Delete(id).ToObservable();

Octokit.Reactive/Helpers/AuthorizationExtensions.cs

@@ -6,31 +6,53 @@ namespace Octokit
 {
     public static class AuthorizationExtensions
     {
+        /// <summary>
+        /// This method will create a new authorization for the specified OAuth application, only if an authorization 
+        /// for that application doesn’t already exist for the user. It returns the user’s token for the application
+        /// if one exists. Otherwise, it creates a new one.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// This method allows the caller to provide a callback which is used to retrieve the two-factor code from
+        /// the user. Typically the callback is used to show some user interface to the user.
+        /// </para>
+        /// <para>
+        /// See <a href="http://developer.github.com/v3/oauth/#list-your-authorizations">API documentation</a> 
+        /// for more details.
+        /// </para>
+        /// </remarks>
+        /// <param name="authorizationsClient">The <see cref="IAuthorizationsClient" /> this method extends</param>
+        /// <param name="clientId">Client ID for the OAuth application that is requesting the token</param>
+        /// <param name="clientSecret">The client secret</param>
+        /// <param name="newAuthorization">Defines the scopes and metadata for the token</param>
+        /// <param name="twoFactorChallengeHandler">Callback used to retrieve the two-factor authentication code
+        /// from the user</param>
+        /// <returns></returns>
         public static IObservable<Authorization> GetOrCreateApplicationAuthentication(
             this IObservableAuthorizationsClient authorizationsClient,
             string clientId,
             string clientSecret,
-            AuthorizationUpdate authorization,
+            NewAuthorization newAuthorization,
             Func<TwoFactorRequiredException, IObservable<TwoFactorChallengeResult>> twoFactorChallengeHandler
             )
         {
             Ensure.ArgumentNotNull(authorizationsClient, "authorizationsClient");
             Ensure.ArgumentNotNullOrEmptyString(clientId, "clientId");
             Ensure.ArgumentNotNullOrEmptyString(clientSecret, "clientSecret");
-            Ensure.ArgumentNotNull(authorization, "authorization");
+            Ensure.ArgumentNotNull(newAuthorization, "authorization");
 
-            return authorizationsClient.GetOrCreateApplicationAuthentication(clientId, clientSecret, authorization)
+            return authorizationsClient.GetOrCreateApplicationAuthentication(clientId, clientSecret, newAuthorization)
                 .Catch<Authorization, TwoFactorRequiredException>(exception => twoFactorChallengeHandler(exception)
                     .SelectMany(result =>
                         result.ResendCodeRequested
                             ? authorizationsClient.GetOrCreateApplicationAuthentication(
                                 clientId,
                                 clientSecret,
-                                authorization,
+                                newAuthorization,
                                 twoFactorChallengeHandler)
                             : authorizationsClient.GetOrCreateApplicationAuthentication(clientId,
                                 clientSecret,
-                                authorization,
+                                newAuthorization,
                                 result.AuthenticationCode)));
         }
     }

Octokit.Reactive/IObservableAuthorizationsClient.cs

@@ -7,9 +7,27 @@ namespace Octokit.Reactive
 {
     public interface IObservableAuthorizationsClient
     {
+        /// <summary>
+        /// Get all <see cref="Authorization"/>s for the authenticated user. This method requires basic auth.
+        /// </summary>
+        /// <remarks>
+        /// See <a href="http://developer.github.com/v3/oauth/#list-your-authorizations">API documentation</a> for more
+        /// details.
+        /// </remarks>
+        /// <returns>An <see cref="Authorization"/></returns>
         [SuppressMessage("Microsoft.Design", "CA1024:UsePropertiesWhereAppropriate", 
             Justification = "It's an API call, so it's not a property.")]
         IObservable<IReadOnlyList<Authorization>> GetAll();
+
+        /// <summary>
+        /// Get a specific <see cref="Authorization"/> for the authenticated user. This method requires basic auth.
+        /// </summary>
+        /// <remarks>
+        /// See <a href="http://developer.github.com/v3/oauth/#get-a-single-authorization">API documentation</a> for
+        /// more details.
+        /// </remarks>
+        /// <param name="id">The id of the <see cref="Authorization"/></param>
+        /// <returns>An <see cref="Authorization"/></returns>
         [SuppressMessage("Microsoft.Naming", "CA1716:IdentifiersShouldNotMatchKeywords", MessageId = "Get",
             Justification = "It's fiiiine. It's fine. Trust us.")]
         IObservable<Authorization> Get(int id);
@@ -19,9 +37,13 @@ namespace Octokit.Reactive
         /// for that application doesn’t already exist for the user. It returns the user’s token for the application
         /// if one exists. Otherwise, it creates one.
         /// </summary>
-        /// <param name="clientId">Client ID for the OAuth application that is requesting the token.</param>
+        /// <remarks>
+        /// See <a href="http://developer.github.com/v3/oauth/#get-or-create-an-authorization-for-a-specific-app">API
+        /// documentation</a> for more details.
+        /// </remarks>
+        /// <param name="clientId">Client ID for the OAuth application that is requesting the token</param>
         /// <param name="clientSecret">The client secret</param>
-        /// <param name="authorization">Defines the scopes and metadata for the token</param>
+        /// <param name="newAuthorization">Defines the scopes and metadata for the token</param>
         /// <exception cref="AuthorizationException">Thrown when the user does not have permission to make 
         /// this request. Check </exception>
         /// <exception cref="TwoFactorRequiredException">Thrown when the current account has two-factor
@@ -30,16 +52,20 @@ namespace Octokit.Reactive
         IObservable<Authorization> GetOrCreateApplicationAuthentication(
             string clientId,
             string clientSecret,
-            AuthorizationUpdate authorization);
+            NewAuthorization newAuthorization);
 
         /// <summary>
         /// This method will create a new authorization for the specified OAuth application, only if an authorization 
         /// for that application doesn’t already exist for the user. It returns the user’s token for the application
         /// if one exists. Otherwise, it creates one.
         /// </summary>
-        /// <param name="clientId">Client ID for the OAuth application that is requesting the token.</param>
+        /// <remarks>
+        /// See <a href="http://developer.github.com/v3/oauth/#get-or-create-an-authorization-for-a-specific-app">API 
+        /// documentation</a> for more details.
+        /// </remarks>
+        /// <param name="clientId">Client ID for the OAuth application that is requesting the token</param>
         /// <param name="clientSecret">The client secret</param>
-        /// <param name="authorization">Defines the scopes and metadata for the token</param>
+        /// <param name="newAuthorization">Defines the scopes and metadata for the token</param>
         /// <param name="twoFactorAuthenticationCode"></param>
         /// <exception cref="AuthorizationException">Thrown when the user does not have permission to make 
         /// this request. Check </exception>
@@ -49,10 +75,29 @@ namespace Octokit.Reactive
         IObservable<Authorization> GetOrCreateApplicationAuthentication(
             string clientId,
             string clientSecret,
-            AuthorizationUpdate authorization,
+            NewAuthorization newAuthorization,
             string twoFactorAuthenticationCode);
-        IObservable<Authorization> Update(int id, AuthorizationUpdate authorization);
-        IObservable<Authorization> Create(AuthorizationUpdate authorization);
+
+        /// <summary>
+        /// Create a new <see cref="Authorization"/>.
+        /// </summary>
+        /// <param name="newAuthorization">Information about the new authorization to create</param>
+        /// <returns></returns>
+        IObservable<Authorization> Create(NewAuthorization newAuthorization);
+
+        /// <summary>
+        /// Update the <see cref="Authorization"/> specified by the id.
+        /// </summary>
+        /// <param name="id">The id of the <see cref="Authorization"/></param>
+        /// <param name="authorizationUpdate">The changes to make to the authorization</param>
+        /// <returns></returns>
+        IObservable<Authorization> Update(int id, AuthorizationUpdate authorizationUpdate);
+        
+        /// <summary>
+        /// Deletes an <see cref="Authorization"/>.
+        /// </summary>
+        /// <param name="id">The systemwide id of the authorization</param>
+        /// <returns></returns>
         IObservable<Unit> Delete(int id);
     }
 }