From 3be89e7c0146f7b7b2d63e27c3e0d3324dda09a3 Mon Sep 17 00:00:00 2001 From: Brendan Forster Date: Sun, 21 Dec 2014 16:17:16 +0930 Subject: [PATCH] document a bunch of the Exceptions namespace --- Octokit/Exceptions/ApiException.cs | 52 +++++++++++++++++++ Octokit/Exceptions/ApiValidationException.cs | 35 +++++++++++-- Octokit/Exceptions/AuthorizationException.cs | 25 ++++++++- Octokit/Exceptions/ForbiddenException.cs | 23 ++++++++ .../LoginAttemptsExceededException.cs | 27 +++++++++- Octokit/Exceptions/NotFoundException.cs | 28 +++++++++- ...PrivateRepositoryQuotaExceededException.cs | 15 ++++-- .../Exceptions/RateLimitExceededException.cs | 21 +++++++- .../Exceptions/RepositoryExistsException.cs | 17 ++++-- .../TwoFactorChallengeFailedException.cs | 21 ++++++++ .../Exceptions/TwoFactorRequiredException.cs | 47 ++++++++++++++++- Octokit/Models/Request/SearchUsersRequest.cs | 24 +++++++++ Octokit/Models/Response/Activity.cs | 3 ++ Octokit/Models/Response/ApiError.cs | 6 +++ 14 files changed, 325 insertions(+), 19 deletions(-) diff --git a/Octokit/Exceptions/ApiException.cs b/Octokit/Exceptions/ApiException.cs index 9e9150ee..b414a246 100644 --- a/Octokit/Exceptions/ApiException.cs +++ b/Octokit/Exceptions/ApiException.cs @@ -6,6 +6,9 @@ using Octokit.Internal; namespace Octokit { + /// + /// Represents errors that occur from the GitHub API. + /// #if !NETFX_CORE [Serializable] #endif @@ -16,25 +19,47 @@ namespace Octokit // This needs to be hard-coded for translating GitHub error messages. static readonly IJsonSerializer _jsonSerializer = new SimpleJsonSerializer(); + /// + /// Constructs an instance of ApiException + /// public ApiException() : this(new ApiResponse()) { } + /// + /// Constructs an instance of ApiException + /// + /// The error message + /// The HTTP status code from the response public ApiException(string message, HttpStatusCode httpStatusCode) : this(new ApiResponse {Body = message, StatusCode = httpStatusCode}) { } + /// + /// Constructs an instance of ApiException + /// + /// The error message + /// The inner exception public ApiException(string message, Exception innerException) : this(new ApiResponse { Body = message }, innerException) { } + /// + /// Constructs an instance of ApiException + /// + /// The HTTP payload from the server public ApiException(IResponse response) : this(response, null) { } + /// + /// Constructs an instance of ApiException + /// + /// The HTTP payload from the server + /// The inner exception public ApiException(IResponse response, Exception innerException) : base(null, innerException) { @@ -44,6 +69,10 @@ namespace Octokit ApiError = GetApiErrorFromExceptionMessage(response); } + /// + /// Constructs an instance of ApiException + /// + /// The inner exception protected ApiException(ApiException innerException) { Ensure.ArgumentNotNull(innerException, "innerException"); @@ -56,8 +85,14 @@ namespace Octokit get { return ApiErrorMessageSafe ?? "An error occurred with this API request"; } } + /// + /// The HTTP status code associated with the repsonse + /// public HttpStatusCode StatusCode { get; private set; } + /// + /// The raw exception payload from the response + /// public ApiError ApiError { get; private set; } static ApiError GetApiErrorFromExceptionMessage(IResponse response) @@ -82,6 +117,17 @@ namespace Octokit } #if !NETFX_CORE + /// + /// Constructs an instance of ApiException. + /// + /// + /// The that holds the + /// serialized object data about the exception being thrown. + /// + /// + /// The that contains + /// contextual information about the source or destination. + /// protected ApiException(SerializationInfo info, StreamingContext context) : base(info, context) { @@ -98,6 +144,12 @@ namespace Octokit } #endif + /// + /// Get the inner error message from the API response + /// + /// + /// Returns null if ApiError is not populated + /// protected string ApiErrorMessageSafe { get diff --git a/Octokit/Exceptions/ApiValidationException.cs b/Octokit/Exceptions/ApiValidationException.cs index 1a8a9028..06e3355e 100644 --- a/Octokit/Exceptions/ApiValidationException.cs +++ b/Octokit/Exceptions/ApiValidationException.cs @@ -8,7 +8,7 @@ using Octokit.Internal; namespace Octokit { /// - /// Represents a validation exception (HTTP STATUS: 422) returned from the API. + /// Represents a HTTP 422 - Unprocessable Entity response returned from the API. /// #if !NETFX_CORE [Serializable] @@ -17,15 +17,28 @@ namespace Octokit Justification = "These exceptions are specific to the GitHub API and not general purpose exceptions")] public class ApiValidationException : ApiException { - public ApiValidationException() : base(new ApiResponse { StatusCode = (HttpStatusCode)422}) + /// + /// Constructs an instance of ApiValidationException + /// + public ApiValidationException() + : base(new ApiResponse { StatusCode = (HttpStatusCode)422 }) { } + /// + /// Constructs an instance of ApiValidationException + /// + /// The HTTP payload from the server public ApiValidationException(IResponse response) : this(response, null) { } + /// + /// Constructs an instance of ApiValidationException + /// + /// The HTTP payload from the server + /// The inner exception public ApiValidationException(IResponse response, Exception innerException) : base(response, innerException) { @@ -33,7 +46,12 @@ namespace Octokit "ApiValidationException created with wrong status code"); } - protected ApiValidationException(ApiValidationException innerException) : base(innerException) + /// + /// Constructs an instance of ApiValidationException + /// + /// The inner exception + protected ApiValidationException(ApiValidationException innerException) + : base(innerException) { } @@ -43,6 +61,17 @@ namespace Octokit } #if !NETFX_CORE + /// + /// Constructs an instance of ApiValidationException + /// + /// + /// The that holds the + /// serialized object data about the exception being thrown. + /// + /// + /// The that contains + /// contextual information about the source or destination. + /// protected ApiValidationException(SerializationInfo info, StreamingContext context) : base(info, context) { diff --git a/Octokit/Exceptions/AuthorizationException.cs b/Octokit/Exceptions/AuthorizationException.cs index 9ae9804d..a27ab32e 100644 --- a/Octokit/Exceptions/AuthorizationException.cs +++ b/Octokit/Exceptions/AuthorizationException.cs @@ -8,7 +8,7 @@ using Octokit.Internal; namespace Octokit { /// - /// Exception thrown when we receive an HttpStatusCode.Unauthorized (HTTP 401) response. + /// Represents a HTTP 401 - Unauthorized response returned from the API. /// #if !NETFX_CORE [Serializable] @@ -17,15 +17,27 @@ namespace Octokit Justification = "These exceptions are specific to the GitHub API and not general purpose exceptions")] public class AuthorizationException : ApiException { + /// + /// Constructs an instance of AuthorizationException + /// public AuthorizationException() : base(new ApiResponse { StatusCode = HttpStatusCode.Unauthorized }) { } + /// + /// Constructs an instance of AuthorizationException + /// + /// The HTTP payload from the server public AuthorizationException(IResponse response) : this(response, null) { } + /// + /// Constructs an instance of AuthorizationException + /// + /// The HTTP payload from the server + /// The inner exception public AuthorizationException(IResponse response, Exception innerException) : base(response, innerException) { @@ -34,6 +46,17 @@ namespace Octokit } #if !NETFX_CORE + /// + /// Constructs an instance of AuthorizationException. + /// + /// + /// The that holds the + /// serialized object data about the exception being thrown. + /// + /// + /// The that contains + /// contextual information about the source or destination. + /// protected AuthorizationException(SerializationInfo info, StreamingContext context) : base(info, context) { diff --git a/Octokit/Exceptions/ForbiddenException.cs b/Octokit/Exceptions/ForbiddenException.cs index efc16737..82934238 100644 --- a/Octokit/Exceptions/ForbiddenException.cs +++ b/Octokit/Exceptions/ForbiddenException.cs @@ -6,6 +6,9 @@ using System.Runtime.Serialization; namespace Octokit { + /// + /// Represents a HTTP 403 - Forbidden response returned from the API. + /// #if !NETFX_CORE [Serializable] #endif @@ -13,10 +16,19 @@ namespace Octokit Justification = "These exceptions are specific to the GitHub API and not general purpose exceptions")] public class ForbiddenException : ApiException { + /// + /// Constructs an instance of ForbiddenException + /// + /// The HTTP payload from the server public ForbiddenException(IResponse response) : this(response, null) { } + /// + /// Constructs an instance of ForbiddenException + /// + /// The HTTP payload from the server + /// The inner exception public ForbiddenException(IResponse response, Exception innerException) : base(response, innerException) { @@ -30,6 +42,17 @@ namespace Octokit } #if !NETFX_CORE + /// + /// Constructs an instance of ForbiddenException + /// + /// + /// The that holds the + /// serialized object data about the exception being thrown. + /// + /// + /// The that contains + /// contextual information about the source or destination. + /// protected ForbiddenException(SerializationInfo info, StreamingContext context) : base(info, context) { diff --git a/Octokit/Exceptions/LoginAttemptsExceededException.cs b/Octokit/Exceptions/LoginAttemptsExceededException.cs index 3d76b7dd..de83c864 100644 --- a/Octokit/Exceptions/LoginAttemptsExceededException.cs +++ b/Octokit/Exceptions/LoginAttemptsExceededException.cs @@ -4,6 +4,9 @@ using System.Runtime.Serialization; namespace Octokit { + /// + /// Represents a "Login Attempts Exceeded" response returned from the API. + /// #if !NETFX_CORE [Serializable] #endif @@ -11,10 +14,20 @@ namespace Octokit Justification = "These exceptions are specific to the GitHub API and not general purpose exceptions")] public class LoginAttemptsExceededException : ForbiddenException { - public LoginAttemptsExceededException(IResponse response) : base(response) + /// + /// Constructs an instance of LoginAttemptsExceededException + /// + /// The HTTP payload from the server + public LoginAttemptsExceededException(IResponse response) + : base(response) { } + /// + /// Constructs an instance of LoginAttemptsExceededException + /// + /// The HTTP payload from the server + /// The inner exception public LoginAttemptsExceededException(IResponse response, Exception innerException) : base(response, innerException) { @@ -26,11 +39,21 @@ namespace Octokit } #if !NETFX_CORE + /// + /// Constructs an instance of LoginAttemptsExceededException + /// + /// + /// The that holds the + /// serialized object data about the exception being thrown. + /// + /// + /// The that contains + /// contextual information about the source or destination. + /// protected LoginAttemptsExceededException(SerializationInfo info, StreamingContext context) : base(info, context) { } #endif - } } diff --git a/Octokit/Exceptions/NotFoundException.cs b/Octokit/Exceptions/NotFoundException.cs index 72995802..a8410303 100644 --- a/Octokit/Exceptions/NotFoundException.cs +++ b/Octokit/Exceptions/NotFoundException.cs @@ -6,6 +6,9 @@ using System.Runtime.Serialization; namespace Octokit { + /// + /// Represents a HTTP 404 - Not Found response returned from the API. + /// #if !NETFX_CORE [Serializable] #endif @@ -13,17 +16,38 @@ namespace Octokit Justification = "These exceptions are specific to the GitHub API and not general purpose exceptions")] public class NotFoundException : ApiException { + /// + /// Constructs an instance of NotFoundException + /// + /// The HTTP payload from the server public NotFoundException(IResponse response) : this(response, null) { } - public NotFoundException(IResponse response, Exception innerException) : base(response, innerException) + /// + /// Constructs an instance of NotFoundException + /// + /// The HTTP payload from the server + /// The inner exception + public NotFoundException(IResponse response, Exception innerException) + : base(response, innerException) { Debug.Assert(response != null && response.StatusCode == HttpStatusCode.NotFound, "NotFoundException created with wrong status code"); } - #if !NETFX_CORE +#if !NETFX_CORE + /// + /// Constructs an instance of NotFoundException + /// + /// + /// The that holds the + /// serialized object data about the exception being thrown. + /// + /// + /// The that contains + /// contextual information about the source or destination. + /// protected NotFoundException(SerializationInfo info, StreamingContext context) : base(info, context) { diff --git a/Octokit/Exceptions/PrivateRepositoryQuotaExceededException.cs b/Octokit/Exceptions/PrivateRepositoryQuotaExceededException.cs index 10bff3cf..1017b5dc 100644 --- a/Octokit/Exceptions/PrivateRepositoryQuotaExceededException.cs +++ b/Octokit/Exceptions/PrivateRepositoryQuotaExceededException.cs @@ -1,10 +1,6 @@ using System; -using System.Collections.Generic; using System.Diagnostics.CodeAnalysis; -using System.Linq; using System.Runtime.Serialization; -using System.Text; -using System.Threading.Tasks; namespace Octokit { @@ -39,6 +35,17 @@ namespace Octokit } #if !NETFX_CORE + /// + /// Constructs an instance of PrivateRepositoryQuotaExceededException + /// + /// + /// The that holds the + /// serialized object data about the exception being thrown. + /// + /// + /// The that contains + /// contextual information about the source or destination. + /// protected PrivateRepositoryQuotaExceededException(SerializationInfo info, StreamingContext context) : base(info, context) { diff --git a/Octokit/Exceptions/RateLimitExceededException.cs b/Octokit/Exceptions/RateLimitExceededException.cs index 54a75580..435517da 100644 --- a/Octokit/Exceptions/RateLimitExceededException.cs +++ b/Octokit/Exceptions/RateLimitExceededException.cs @@ -2,7 +2,6 @@ using System.Collections.Generic; using System.Diagnostics.CodeAnalysis; using System.Runtime.Serialization; -using Octokit.Internal; namespace Octokit { @@ -25,10 +24,19 @@ namespace Octokit { readonly RateLimit _rateLimit; + /// + /// Constructs an instance of RateLimitExceededException + /// + /// The HTTP payload from the server public RateLimitExceededException(IResponse response) : this(response, null) { } + /// + /// Constructs an instance of RateLimitExceededException + /// + /// The HTTP payload from the server + /// The inner exception public RateLimitExceededException(IResponse response, Exception innerException) : base(response, innerException) { Ensure.ArgumentNotNull(response, "response"); @@ -68,6 +76,17 @@ namespace Octokit } #if !NETFX_CORE + /// + /// Constructs an instance of RateLimitExceededException + /// + /// + /// The that holds the + /// serialized object data about the exception being thrown. + /// + /// + /// The that contains + /// contextual information about the source or destination. + /// protected RateLimitExceededException(SerializationInfo info, StreamingContext context) : base(info, context) { diff --git a/Octokit/Exceptions/RepositoryExistsException.cs b/Octokit/Exceptions/RepositoryExistsException.cs index 9d19bbdd..3a0de556 100644 --- a/Octokit/Exceptions/RepositoryExistsException.cs +++ b/Octokit/Exceptions/RepositoryExistsException.cs @@ -1,11 +1,7 @@ using System; -using System.Collections.Generic; using System.Diagnostics.CodeAnalysis; using System.Globalization; -using System.Linq; using System.Runtime.Serialization; -using System.Text; -using System.Threading.Tasks; namespace Octokit { @@ -19,7 +15,7 @@ namespace Octokit Justification = "These exceptions are specific to the GitHub API and not general purpose exceptions")] public class RepositoryExistsException : ApiValidationException { - string _message; + readonly string _message; /// /// Constructs an instance of RepositoryExistsException. @@ -86,6 +82,17 @@ namespace Octokit public bool OwnerIsOrganization { get; private set; } #if !NETFX_CORE + /// + /// Constructs an instance of RepositoryExistsException. + /// + /// + /// The that holds the + /// serialized object data about the exception being thrown. + /// + /// + /// The that contains + /// contextual information about the source or destination. + /// protected RepositoryExistsException(SerializationInfo info, StreamingContext context) : base(info, context) { diff --git a/Octokit/Exceptions/TwoFactorChallengeFailedException.cs b/Octokit/Exceptions/TwoFactorChallengeFailedException.cs index 0afa790e..7c67b489 100644 --- a/Octokit/Exceptions/TwoFactorChallengeFailedException.cs +++ b/Octokit/Exceptions/TwoFactorChallengeFailedException.cs @@ -7,17 +7,27 @@ using Octokit.Internal; namespace Octokit { #if !NETFX_CORE + /// + /// Represents a failed 2FA challenge from the API + /// [Serializable] #endif [SuppressMessage("Microsoft.Design", "CA1032:ImplementStandardExceptionConstructors", Justification = "These exceptions are specific to the GitHub API and not general purpose exceptions")] public class TwoFactorChallengeFailedException : AuthorizationException { + /// + /// Constructs an instance of TwoFactorChallengeFailedException + /// public TwoFactorChallengeFailedException() : base(new ApiResponse { StatusCode = HttpStatusCode.Unauthorized }) { } + /// + /// Constructs an instance of TwoFactorChallengeFailedException + /// + /// The inner exception public TwoFactorChallengeFailedException(Exception innerException) : base(new ApiResponse { StatusCode = HttpStatusCode.Unauthorized }, innerException) { @@ -29,6 +39,17 @@ namespace Octokit } #if !NETFX_CORE + /// + /// Constructs an instance of TwoFactorChallengeFailedException + /// + /// + /// The that holds the + /// serialized object data about the exception being thrown. + /// + /// + /// The that contains + /// contextual information about the source or destination. + /// protected TwoFactorChallengeFailedException(SerializationInfo info, StreamingContext context) : base(info, context) { diff --git a/Octokit/Exceptions/TwoFactorRequiredException.cs b/Octokit/Exceptions/TwoFactorRequiredException.cs index 3b4e3384..1763749a 100644 --- a/Octokit/Exceptions/TwoFactorRequiredException.cs +++ b/Octokit/Exceptions/TwoFactorRequiredException.cs @@ -7,6 +7,9 @@ using Octokit.Internal; namespace Octokit { + /// + /// + /// #if !NETFX_CORE [Serializable] #endif @@ -14,15 +17,27 @@ namespace Octokit Justification = "These exceptions are specific to the GitHub API and not general purpose exceptions")] public class TwoFactorRequiredException : AuthorizationException { + /// + /// Constructs an instance of TwoFactorRequiredException. + /// public TwoFactorRequiredException() : this(TwoFactorType.None) { } + /// + /// Constructs an instance of TwoFactorRequiredException. + /// + /// Expected 2FA response type public TwoFactorRequiredException(TwoFactorType twoFactorType) : this(new ApiResponse { StatusCode = HttpStatusCode.Unauthorized}, twoFactorType) { } + /// + /// Constructs an instance of TwoFactorRequiredException. + /// + /// The HTTP payload from the server + /// Expected 2FA response type public TwoFactorRequiredException(IResponse response, TwoFactorType twoFactorType) : base(response) { Debug.Assert(response != null && response.StatusCode == HttpStatusCode.Unauthorized, @@ -37,6 +52,17 @@ namespace Octokit } #if !NETFX_CORE + /// + /// Constructs an instance of TwoFactorRequiredException. + /// + /// + /// The that holds the + /// serialized object data about the exception being thrown. + /// + /// + /// The that contains + /// contextual information about the source or destination. + /// protected TwoFactorRequiredException(SerializationInfo info, StreamingContext context) : base(info, context) { @@ -51,14 +77,33 @@ namespace Octokit } #endif + /// + /// Expected 2FA response type + /// public TwoFactorType TwoFactorType { get; private set; } } + /// + /// Methods for receiving 2FA authentication codes + /// public enum TwoFactorType { + /// + /// No method configured + /// None, + /// + /// Unknown method + /// Unknown, - [SuppressMessage("Microsoft.Naming", "CA1704:IdentifiersShouldBeSpelledCorrectly", MessageId = "Sms")] Sms, + /// + /// Receive via SMS + /// + [SuppressMessage("Microsoft.Naming", "CA1704:IdentifiersShouldBeSpelledCorrectly", MessageId = "Sms")] + Sms, + /// + /// Receive via application + /// AuthenticatorApp } } diff --git a/Octokit/Models/Request/SearchUsersRequest.cs b/Octokit/Models/Request/SearchUsersRequest.cs index 2fee45c1..e5e6d062 100644 --- a/Octokit/Models/Request/SearchUsersRequest.cs +++ b/Octokit/Models/Request/SearchUsersRequest.cs @@ -135,21 +135,45 @@ namespace Octokit } } + /// + /// Account Type used to filter search result + /// public enum AccountType { + /// + /// User account + /// User, + /// + /// Organization account + /// Org } + /// + /// User type to filter search results + /// public enum UserInQualifier { + /// + /// Search by the username + /// [SuppressMessage("Microsoft.Naming", "CA1702:CompoundWordsShouldBeCasedCorrectly", MessageId = "Username")] Username, + /// + /// Search by the user's email address + /// Email, + /// + /// Search by the user's full name + /// [SuppressMessage("Microsoft.Naming", "CA1704:IdentifiersShouldBeSpelledCorrectly", MessageId = "Fullname")] Fullname } + /// + /// + /// public enum UsersSearchSort { Followers, diff --git a/Octokit/Models/Response/Activity.cs b/Octokit/Models/Response/Activity.cs index d4b745ac..c6805ef9 100644 --- a/Octokit/Models/Response/Activity.cs +++ b/Octokit/Models/Response/Activity.cs @@ -5,6 +5,9 @@ using System.Globalization; namespace Octokit { + /// + /// An entry in the activity event stream + /// [DebuggerDisplay("{DebuggerDisplay,nq}")] public class Activity { diff --git a/Octokit/Models/Response/ApiError.cs b/Octokit/Models/Response/ApiError.cs index 69204bcf..af23c717 100644 --- a/Octokit/Models/Response/ApiError.cs +++ b/Octokit/Models/Response/ApiError.cs @@ -4,6 +4,9 @@ using System.Diagnostics.CodeAnalysis; namespace Octokit { + /// + /// Error payload from the API reposnse + /// #if !NETFX_CORE [Serializable] #endif @@ -20,6 +23,9 @@ namespace Octokit public string DocumentationUrl { get; set; } // TODO: This ought to be an IReadOnlyList but we need to add support to SimpleJson for that. + /// + /// Additional details about the error + /// [SuppressMessage("Microsoft.Usage", "CA2227:CollectionPropertiesShouldBeReadOnly")] public IList Errors { get; set; } }