Clean up xmldoc for clients

src/Auth0.AuthenticationApi/AuthenticationApiClient.cs

@@ -1,10 +1,10 @@
-using System;
+using Auth0.AuthenticationApi.Builders;
+using Auth0.AuthenticationApi.Models;
+using Auth0.Core.Http;
+using System;
 using System.Collections.Generic;
 using System.Net.Http;
 using System.Threading.Tasks;
-using Auth0.AuthenticationApi.Builders;
-using Auth0.AuthenticationApi.Models;
-using Auth0.Core.Http;
 
 namespace Auth0.AuthenticationApi
 {
@@ -16,9 +16,6 @@ namespace Auth0.AuthenticationApi
     /// </remarks>
     public class AuthenticationApiClient : IAuthenticationApiClient
     {
-        /// <summary>
-        /// The base URI
-        /// </summary>
         private readonly Uri _baseUri;
 
         private AuthenticationApiClient(Uri baseUri, ApiConnection connection)
@@ -336,7 +333,13 @@ public async Task<AccessTokenResponse> GetTokenAsync(ResourceOwnerTokenRequest r
             return response;
         }
 
-        /// <inheritdoc />
+
+        /// <summary>
+        /// Gets information about the last API call made using this client.
+        /// </summary>
+        /// <returns>
+        /// A <see cref="ApiInfo"/> containing information about the last API call made.
+        /// </returns>
         public ApiInfo GetLastApiInfo()
         {
             return Connection.ApiInfo;
@@ -414,7 +417,7 @@ public Task<PasswordlessSmsResponse> StartPasswordlessSmsFlowAsync(PasswordlessS
         /// Unlinks a secondary account from a primary account.
         /// </summary>
         /// <param name="request">The <see cref="UnlinkUserRequest"/> containing the information of the accounts to unlink.</param>
-        /// <returns>Nothing</returns>
+        /// <returns>A <see cref="Task"/> that represents the asynchronous unlink operation.</returns>
         public async Task UnlinkUserAsync(UnlinkUserRequest request)
         {
             await Connection.PostAsync<object>("unlink", request, null, null, null, null, null).ConfigureAwait(false);

src/Auth0.Core/Http/ApiConnection.cs

@@ -1,17 +1,17 @@
+using Auth0.Core.Exceptions;
+using Newtonsoft.Json;
 using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Net.Http;
 using System.Reflection;
 using System.Text;
 using System.Threading.Tasks;
-using Auth0.Core.Exceptions;
-using Newtonsoft.Json;
 
 namespace Auth0.Core.Http
 {
     /// <summary>
-    /// The communication layer between the various API clients and the actual API backend.
+    /// The communication layer between the API clients and the HTTP REST backend.
     /// </summary>
     public class ApiConnection : IApiConnection, IDisposable
     {
@@ -26,12 +26,24 @@ public class ApiConnection : IApiConnection, IDisposable
         /// </summary>
         public ApiInfo ApiInfo { get; private set; }
 
+        /// <summary>
+        /// Creates a new instance of ApiConnection using an optional <see cref="HttpMessageHandler"/>.
+        /// </summary>
+        /// <param name="token">A valid Auth0 Management API v2 token.</param>
+        /// <param name="baseUrl">The URL of the tenant to manage.</param>
+        /// <param name="handler">An optional <see cref="HttpMessageHandler"/> to modify outgoing requests.</param>
         public ApiConnection(string token, string baseUrl, HttpMessageHandler handler = null)
             : this(token, baseUrl, new HttpClient(handler ?? new HttpClientHandler()))
         {
             _disposeHttpClient = true;
         }
 
+        /// <summary>
+        /// Creates a new instance of ApiConnection using a provided <see cref="HttpClient"/>.
+        /// </summary>
+        /// <param name="token">A valid Auth0 Management API v2 token.</param>
+        /// <param name="baseUrl">The URL of the tenant to manage.</param>
+        /// <param name="httpClient">A <see cref="HttpClient"/> used to send outgoing requests.</param>
         public ApiConnection(string token, string baseUrl, HttpClient httpClient)
         {
             _token = token;
@@ -81,14 +93,6 @@ private void ApplyHeaders(HttpRequestMessage message, IDictionary<string, object
                         message.Headers.Add(pair.Key, pair.Value.ToString());
         }
 
-        /// <summary>
-        /// Builds the content of the message. This will build the appropriate <see cref="HttpContent" /> for the request based
-        /// on the type of the parameters passed in.
-        /// </summary>
-        /// <param name="body">The body.</param>
-        /// <param name="parameters">The parameters.</param>
-        /// <param name="fileParameters">The file parameters.</param>
-        /// <returns>HttpContent.</returns>
         private HttpContent BuildMessageContent(object body, IDictionary<string, object> parameters,
             IList<FileUploadParameter> fileParameters)
         {
@@ -123,13 +127,6 @@ private HttpContent BuildMessageContent(object body, IDictionary<string, object>
             }), Encoding.UTF8, "application/json");
         }
 
-        /// <summary>
-        /// Builds up the URL for the request by substituting values for URL segments and adding query string parameters.
-        /// </summary>
-        /// <param name="resource">The resource.</param>
-        /// <param name="urlSegments">The URL segments.</param>
-        /// <param name="queryStrings">The query strings.</param>
-        /// <returns>Uri.</returns>
         private Uri BuildRequestUri(string resource, IDictionary<string, string> urlSegments,
             IDictionary<string, string> queryStrings)
         {
@@ -143,7 +140,7 @@ private Uri BuildRequestUri(string resource, IDictionary<string, string> urlSegm
         /// <param name="resource">The resource.</param>
         /// <param name="urlSegments">The URL segments.</param>
         /// <param name="queryStrings"></param>
-        /// <returns>Task&lt;T&gt;.</returns>
+        /// <returns>A <see cref="Task{T}"/> that represents the asynchronous Delete operation.</returns>
         public async Task<T> DeleteAsync<T>(string resource, IDictionary<string, string> urlSegments,
             IDictionary<string, string> queryStrings) where T : class
         {
@@ -166,7 +163,7 @@ public async Task<T> DeleteAsync<T>(string resource, IDictionary<string, string>
         /// <param name="body">The body.</param>
         /// <param name="urlSegments">The URL segments.</param>
         /// <param name="queryStrings"></param>
-        /// <returns>Task&lt;T&gt;.</returns>
+        /// <returns>A <see cref="Task{T}"/> that represents the asynchronous Delete operation.</returns>
         public async Task<T> DeleteAsync<T>(string resource, object body, IDictionary<string, string> urlSegments, IDictionary<string, string> queryStrings) where T : class
         {
             return await RunAsync<T>(resource,
@@ -210,13 +207,6 @@ public async Task<T> GetAsync<T>(string resource, IDictionary<string, string> ur
                 converters).ConfigureAwait(false);
         }
 
-        /// <summary>
-        /// Handles errors returned from the API. It will check the response code, deserialize any relevant JSON error payload
-        /// and throw an appropriate exception.
-        /// </summary>
-        /// <param name="response">The <see cref="HttpResponseMessage" /> returned from the API.</param>
-        /// <returns>A <see cref="Task" />.</returns>
-        /// <exception cref="ApiException"></exception>
         private async Task HandleErrors(HttpResponseMessage response)
         {
             if (!response.IsSuccessStatusCode)
@@ -251,13 +241,13 @@ private async Task HandleErrors(HttpResponseMessage response)
         }
 
         /// <summary>
-        /// Performs an HTTP PATCH.
+        /// Performs an HTTP PATCH operation.
         /// </summary>
         /// <typeparam name="T"></typeparam>
         /// <param name="resource">The resource.</param>
         /// <param name="body">The body.</param>
         /// <param name="urlSegments">The URL segments.</param>
-        /// <returns>Task&lt;T&gt;.</returns>
+        /// <returns>A <see cref="Task{T}"/> that represents the asynchronous Patch operation.</returns>
         public async Task<T> PatchAsync<T>(string resource, object body, Dictionary<string, string> urlSegments)
             where T : class
         {
@@ -283,7 +273,7 @@ public async Task<T> PatchAsync<T>(string resource, object body, Dictionary<stri
         /// <param name="urlSegments">The URL segments.</param>
         /// <param name="headers">The headers.</param>
         /// <param name="queryStrings">The query strings.</param>
-        /// <returns>Task&lt;T&gt;.</returns>
+        /// <returns>A <see cref="Task{T}"/> that represents the asynchronous Post operation.</returns>
         public async Task<T> PostAsync<T>(string resource, object body, IDictionary<string, object> parameters,
             IList<FileUploadParameter> fileParameters, IDictionary<string, string> urlSegments,
             IDictionary<string, object> headers, IDictionary<string, string> queryStrings) where T : class
@@ -310,7 +300,7 @@ public async Task<T> PostAsync<T>(string resource, object body, IDictionary<stri
         /// <param name="urlSegments">The URL segments.</param>
         /// <param name="headers">The headers.</param>
         /// <param name="queryStrings">The query strings.</param>
-        /// <returns>Task&lt;T&gt;.</returns>
+        /// <returns>A <see cref="Task{T}"/> that represents the asynchronous Put operation.</returns>
         public async Task<T> PutAsync<T>(string resource, object body, IDictionary<string, object> parameters,
             IList<FileUploadParameter> fileParameters, IDictionary<string, string> urlSegments,
             IDictionary<string, object> headers, IDictionary<string, string> queryStrings) where T : class
@@ -340,7 +330,7 @@ public async Task<T> PutAsync<T>(string resource, object body, IDictionary<strin
         /// <param name="headers">The headers.</param>
         /// <param name="fileParameters">The file parameters.</param>
         /// <param name="converters">The list of <see cref="JsonConverter" /> to use during deserialization.</param>
-        /// <returns>Task&lt;T&gt;.</returns>
+        /// <returns>A <see cref="Task{T}"/> that represents the asynchronous Run operation.</returns>
         private async Task<T> RunAsync<T>(string resource, HttpMethod httpMethod, object body,
             IDictionary<string, string> urlSegments, IDictionary<string, string> queryStrings,
             IDictionary<string, object> parameters, IDictionary<string, object> headers,

src/Auth0.ManagementApi/Clients/BlacklistedTokensClient.cs

@@ -22,7 +22,7 @@ public BlacklistedTokensClient(IApiConnection connection)
         /// <summary>
         /// Gets all the blacklisted claims.
         /// </summary>
-        /// <param name="aud">The aud claim for which you want to get blacklisted tokens. This is your API Key.</param>
+        /// <param name="aud">The JWT's aud claim. The client_id of the client for which it was issued.</param>
         /// <returns>A list of <see cref="BlacklistedToken"/> objects.</returns>
         public Task<IList<BlacklistedToken>> GetAllAsync(string aud)
         {
@@ -37,7 +37,7 @@ public Task<IList<BlacklistedToken>> GetAllAsync(string aud)
         /// Blacklists a JWT token.
         /// </summary>
         /// <param name="request">The <see cref="BlacklistedTokenCreateRequest"/> containing the information of the token to blacklist.</param>
-        /// <returns>A <see cref="Task"/> indicating the request completion.</returns>
+        /// <returns>A <see cref="Task"/> that represents the asynchronous create operation.</returns>
         public Task CreateAsync(BlacklistedTokenCreateRequest request)
         {
             return Connection.PostAsync<Client>("blacklists/tokens", request, null, null, null, null, null);

src/Auth0.ManagementApi/Clients/ClientBase.cs

@@ -8,7 +8,7 @@ namespace Auth0.ManagementApi.Clients
     public class ClientBase
     {
         /// <summary>
-        /// The <see cref="IApiConnection"/> which is used to make all HTTPS REST calls.
+        /// The <see cref="IApiConnection"/> which is used to make all REST calls.
         /// </summary>
         internal IApiConnection Connection { get; }
 

src/Auth0.ManagementApi/Clients/ClientGrantsClient.cs

@@ -36,7 +36,7 @@ public Task<ClientGrant> CreateAsync(ClientGrantCreateRequest request)
         /// Deletes a client grant.
         /// </summary>
         /// <param name="id">The identifier of the Client Grant to delete.</param>
-        /// <returns>A <see cref="Task"/> indicating the request completion.</returns>
+        /// <returns>A <see cref="Task"/> that represents the asynchronous delete operation.</returns>
         public Task DeleteAsync(string id)
         {
             return Connection.DeleteAsync<object>("client-grants/{id}", 
@@ -51,7 +51,7 @@ public Task DeleteAsync(string id)
         /// </summary>
         /// <param name="request">Specifies criteria to use when querying client grants.</param>
         /// <param name="pagination">Specifies <see cref="PaginationInfo"/> to use in requesting paged results.</param>
-        /// <returns>A <see cref="IPagedList"/> containing the matching <see cref="ClientGrant"/> instances.</returns>
+        /// <returns>A <see cref="IPagedList{ClientGrant}"/> containing the client grants requested.</returns>
         public Task<IPagedList<ClientGrant>> GetAllAsync(GetClientGrantsRequest request, PaginationInfo pagination)
         {
             if (request == null)

src/Auth0.ManagementApi/Clients/ClientsClient.cs

@@ -39,7 +39,7 @@ public Task<Client> CreateAsync(ClientCreateRequest request)
         /// Deletes a client and all its related assets (like rules, connections, etc) given its id.
         /// </summary>
         /// <param name="id">The id of the client to delete.</param>
-        /// <returns>A <see cref="Task"/> indicating the request completion.</returns>
+        /// <returns>A <see cref="Task"/> that represents the asynchronous delete operation.</returns>
         public Task DeleteAsync(string id)
         {
             return Connection.DeleteAsync<object>("clients/{id}", 
@@ -111,7 +111,7 @@ public Task<Client> GetAsync(string id, string fields = null, bool includeFields
         /// <summary>
         /// Rotate a client secret. The generated secret is NOT base64 encoded.
         /// </summary>
-        /// <param name="id">The id of the client which secret needs to be rotated</param>
+        /// <param name="id">The id of the client which secret needs to be rotated.</param>
         /// <returns>The <see cref="Client"/> that has had its secret rotated.</returns>
         public Task<Client> RotateClientSecret(string id)
         {

src/Auth0.ManagementApi/Clients/ConnectionsClient.cs

@@ -36,6 +36,7 @@ public Task<Connection> CreateAsync(ConnectionCreateRequest request)
         /// Deletes a connection and all its users.
         /// </summary>
         /// <param name="id">The id of the connection to delete.</param>
+        /// <returns>A <see cref="Task"/> that represents the asynchronous delete operation.</returns>
         public Task DeleteAsync(string id)
         {
             return Connection.DeleteAsync<object>("connections/{id}", new Dictionary<string, string>
@@ -45,14 +46,14 @@ public Task DeleteAsync(string id)
         }
 
         /// <summary>
-        /// Deletes a specified connection user by its email.
+        /// Deletes a specified connection user by its <paramref name="email"/>.
         /// </summary>
         /// <remarks>
         /// Currently only database connections are supported and you cannot delete all users from specific connection.
         /// </remarks>
-        /// <param name="id">The identifier of the connection</param>
-        /// <param name="email">The email of the user to delete</param>
-        /// <returns></returns>
+        /// <param name="id">The identifier of the connection.</param>
+        /// <param name="email">The email of the user to delete.</param>
+        /// <returns>A <see cref="Task"/> that represents the asynchronous delete operation.</returns>
         public Task DeleteUserAsync(string id, string email)
         {
             return Connection.DeleteAsync<object>("connections/{id}/users",
@@ -67,7 +68,7 @@ public Task DeleteUserAsync(string id, string email)
         }
 
         /// <summary>
-        /// Retrieves a connection by its <paramref name="id"/>
+        /// Retrieves a connection by its <paramref name="id"/>.
         /// </summary>
         /// <param name="id">The id of the connection to retrieve.</param>
         /// <param name="fields">A comma separated list of fields to include or exclude (depending on include_fields) from the result, empty to retrieve all fields.</param>

src/Auth0.ManagementApi/Clients/CustomDomainsClient.cs

@@ -23,7 +23,7 @@ internal CustomDomainsClient(IApiConnection connection)
         /// Creates a new custom domain and returns it.
         /// </summary>
         /// <param name="request">A <see cref="CustomDomainCreateRequest"/> representing the new domain.</param>
-        /// <returns>The new domain.</returns>
+        /// <returns>The <see cref="CustomDomain"/> containing the newly created custom domain.</returns>
         /// <remarks>The custom domain will need to be verified before it starts accepting requests.</remarks>
         public Task<CustomDomain> CreateAsync(CustomDomainCreateRequest request)
         {
@@ -34,7 +34,7 @@ public Task<CustomDomain> CreateAsync(CustomDomainCreateRequest request)
         /// Deletes a custom domain by its ID.
         /// </summary>
         /// <param name="id">The ID of the domain to delete.</param>
-        /// <returns></returns>
+        /// <returns>A <see cref="Task"/> that represents the asyncronous delete operation.</returns>
         /// <remarks>When deleted, Auth0 will stop serving requests for this domain.</remarks>
         public Task DeleteAsync(string id)
         {
@@ -48,7 +48,7 @@ public Task DeleteAsync(string id)
         /// <summary>
         /// Retrieves the status of every custom domain.
         /// </summary>
-        /// <returns>The list of custom domains</returns>
+        /// <returns>A <see cref="IList{CustomDomain}"/> containing the details of every custom domain.
         public Task<IList<CustomDomain>> GetAllAsync()
         {
             return Connection.GetAsync<IList<CustomDomain>>("custom-domains", null, null, null, null);
@@ -58,7 +58,7 @@ public Task<IList<CustomDomain>> GetAllAsync()
         /// Retrieves a custom domain status by its ID
         /// </summary>
         /// <param name="id">The ID of the domain to retrieve.</param>
-        /// <returns>The domain.</returns>
+        /// <returns>The <see cref="CustomDomain"/> that was requested.</returns>
         public Task<CustomDomain> GetAsync(string id)
         {
             return Connection.GetAsync<CustomDomain>("custom-domains/{id}",
@@ -73,7 +73,7 @@ public Task<CustomDomain> GetAsync(string id)
         /// Run the verification process for the custom domain. 
         /// </summary>
         /// <param name="id">The ID of the domain to verify.</param>
-        /// <returns></returns>
+        /// <returns>The <see cref="CustomDomainVerification"/> that was requested.</returns>
         public Task<CustomDomainVerificationResponse> VerifyAsync(string id)
         {
             return Connection.PostAsync<CustomDomainVerificationResponse>("custom-domains/{id}/verify", null, null, null,