From 5bd4952be3b5e8e44e887d0cbbba6e29dce0e66e Mon Sep 17 00:00:00 2001 From: Jezz Santos Date: Sun, 1 Oct 2023 18:13:17 +1300 Subject: [PATCH] Fixed up all missing code documentation --- docs/decisions/0045-modularization.md | 2 +- src/Application.Common/Caller.cs | 3 ++ ...tensions.cs => CallerContextExtensions.cs} | 2 +- src/Application.Interfaces/GetOptions.cs | 6 ++++ .../GetOptionsExtensions.cs | 3 ++ src/Application.Interfaces/SearchOptions.cs | 6 ++++ src/Common/Error.cs | 30 +++++++++++++++++++ src/Domain.Common/UserRoles.cs | 3 ++ src/Domain.Interfaces/CallerConstants.cs | 6 ++++ .../HasGetOptions.cs | 3 ++ .../JsonDateTimeConverter.cs | 3 ++ .../XmlHttpResult.cs | 6 ++++ .../EmptyResponse.cs | 3 ++ .../HttpError.cs | 25 +++++++++++----- .../IWebSearchRequest.cs | 3 ++ .../IWebSearchResponse.cs | 3 ++ .../SearchRequest.cs | 3 ++ .../SearchResponse.cs | 3 ++ .../MissingDocsAnalyzer.cs | 1 + 19 files changed, 104 insertions(+), 10 deletions(-) rename src/Application.Common/{CurrentCallerExtensions.cs => CallerContextExtensions.cs} (94%) diff --git a/docs/decisions/0045-modularization.md b/docs/decisions/0045-modularization.md index f56dadc2..f20ce23f 100644 --- a/docs/decisions/0045-modularization.md +++ b/docs/decisions/0045-modularization.md @@ -40,7 +40,7 @@ The options are: - At the start of building a SaaS product, the bounded contexts of the software are largely unknown, but what is known are the use cases being designed for in the early days. Subdomains will naturally evolve from grouping those use cases around specific aggregates/resources, as they are explored and built out. - - > Bounded contexts, at the beginning of a software build, pretty much represent a whole subdomain itself. More sophisticated definitions of bounded contexts be derived far later in the journey, when more about the domain is learned. + - > Bounded contexts, at the beginning of a software build, pretty much represent a whole subdomain itself. More sophisticated definitions of bounded contexts be derived far later in the journey, when more about the domain is learned. - REST resources are designed to expose a remote HTTP API to remote consumers. It is not the only way to interop with a SaaS product. Service buses, event hubs, queues, IoT, and other infrastructure are also interop mechanisms. REST resources are designed around real-world processes and use cases, so the overlap is close to aggregates and subdomains, but not precisely the same. diff --git a/src/Application.Common/Caller.cs b/src/Application.Common/Caller.cs index 1f9630ee..e4c6be57 100644 --- a/src/Application.Common/Caller.cs +++ b/src/Application.Common/Caller.cs @@ -74,6 +74,9 @@ public static ICallerContext CreateAsServiceClient() return new ServiceClientAccountCaller(); } + /// + /// Returns a newly generated ID for the call + /// public static string GenerateCallId() { return $"{Guid.NewGuid():N}"; diff --git a/src/Application.Common/CurrentCallerExtensions.cs b/src/Application.Common/CallerContextExtensions.cs similarity index 94% rename from src/Application.Common/CurrentCallerExtensions.cs rename to src/Application.Common/CallerContextExtensions.cs index 746a7c33..c017df07 100644 --- a/src/Application.Common/CurrentCallerExtensions.cs +++ b/src/Application.Common/CallerContextExtensions.cs @@ -6,7 +6,7 @@ namespace Application.Common; -public static class CurrentCallerExtensions +public static class CallerContextExtensions { /// /// Returns the call context from the context diff --git a/src/Application.Interfaces/GetOptions.cs b/src/Application.Interfaces/GetOptions.cs index 64dd7b46..846bf3a0 100644 --- a/src/Application.Interfaces/GetOptions.cs +++ b/src/Application.Interfaces/GetOptions.cs @@ -3,6 +3,9 @@ namespace Application.Interfaces; +/// +/// Defines options for embedding resources in GET REST API calls +/// public class GetOptions { public const string EmbedRequestParamDelimiter = ","; @@ -50,6 +53,9 @@ public static GetOptions Custom(params Expression +/// Defines the options for expanding child resources in REST responses +/// public enum ExpandOptions { None = 0, diff --git a/src/Application.Interfaces/GetOptionsExtensions.cs b/src/Application.Interfaces/GetOptionsExtensions.cs index f955e2e8..3d5ef55b 100644 --- a/src/Application.Interfaces/GetOptionsExtensions.cs +++ b/src/Application.Interfaces/GetOptionsExtensions.cs @@ -6,6 +6,9 @@ namespace Application.Interfaces; public static class GetOptionsExtensions { + /// + /// Converts the expressions to names of the properties + /// internal static List ReferencesToNames( this Expression>[] propertyReferences) { diff --git a/src/Application.Interfaces/SearchOptions.cs b/src/Application.Interfaces/SearchOptions.cs index b83f44ac..363c24e5 100644 --- a/src/Application.Interfaces/SearchOptions.cs +++ b/src/Application.Interfaces/SearchOptions.cs @@ -160,12 +160,18 @@ public Sorting(string by, SortDirection direction = SortDirection.Ascending) public SortDirection Direction { get; } + /// + /// Creates a new for the and + /// public static Sorting ByField(string field, SortDirection direction = SortDirection.Ascending) { return new Sorting(field, direction); } } +/// +/// Defines the sorting direction +/// public enum SortDirection { Ascending = 0, diff --git a/src/Common/Error.cs b/src/Common/Error.cs index 3a4b316b..2a05aa9d 100644 --- a/src/Common/Error.cs +++ b/src/Common/Error.cs @@ -15,51 +15,81 @@ private Error(ErrorCode code, string? message = null) public ErrorCode Code { get; } + /// + /// Creates a error + /// public static Error Validation(string? message = null) { return new Error(ErrorCode.Validation, message); } + /// + /// Creates a error + /// public static Error RuleViolation(string? message = null) { return new Error(ErrorCode.RuleViolation, message); } + /// + /// Creates a error + /// public static Error RoleViolation(string? message = null) { return new Error(ErrorCode.RoleViolation, message); } + /// + /// Creates a error + /// public static Error PreconditionViolation(string? message = null) { return new Error(ErrorCode.PreconditionViolation, message); } + /// + /// Creates a error + /// public static Error EntityNotFound(string? message = null) { return new Error(ErrorCode.EntityNotFound, message); } + /// + /// Creates a error + /// public static Error EntityExists(string? message = null) { return new Error(ErrorCode.EntityExists, message); } + /// + /// Creates a error + /// public static Error NotAuthenticated(string? message = null) { return new Error(ErrorCode.NotAuthenticated, message); } + /// + /// Creates a error + /// public static Error ForbiddenAccess(string? message = null) { return new Error(ErrorCode.ForbiddenAccess, message); } + /// + /// Creates a error + /// public static Error NotSubscribed(string? message = null) { return new Error(ErrorCode.NotSubscribed, message); } + /// + /// Creates a error + /// public static Error Unexpected(string? message = null) { return new Error(ErrorCode.Unexpected, message); diff --git a/src/Domain.Common/UserRoles.cs b/src/Domain.Common/UserRoles.cs index e05c37a5..e8236dd5 100644 --- a/src/Domain.Common/UserRoles.cs +++ b/src/Domain.Common/UserRoles.cs @@ -26,6 +26,9 @@ public static class UserRoles #endif }; + /// + /// Whether the is an assignable role + /// public static bool IsUserAssignableRole(string role) { return UserAssignableRoles.ContainsIgnoreCase(role); diff --git a/src/Domain.Interfaces/CallerConstants.cs b/src/Domain.Interfaces/CallerConstants.cs index c36ff4a2..87d1023d 100644 --- a/src/Domain.Interfaces/CallerConstants.cs +++ b/src/Domain.Interfaces/CallerConstants.cs @@ -27,11 +27,17 @@ public const string ExternalWebhookAccountUserId }; + /// + /// Whether the user is the + /// public static bool IsAnonymousUser(string userId) { return userId == AnonymousUserId; } + /// + /// Whether the user is one of the + /// public static bool IsServiceAccount(string userId) { return ServiceAccounts.Contains(userId); diff --git a/src/Infrastructure.WebApi.Common/HasGetOptions.cs b/src/Infrastructure.WebApi.Common/HasGetOptions.cs index fd9e7e58..50c0a597 100644 --- a/src/Infrastructure.WebApi.Common/HasGetOptions.cs +++ b/src/Infrastructure.WebApi.Common/HasGetOptions.cs @@ -17,6 +17,9 @@ public class HasGetOptions : IHasGetOptions public string? Embed { get; set; } + /// + /// Converts the to a + /// public static HasGetOptions Custom(params Expression>[] resourceProperties) { return GetOptions.Custom(resourceProperties) diff --git a/src/Infrastructure.WebApi.Common/JsonDateTimeConverter.cs b/src/Infrastructure.WebApi.Common/JsonDateTimeConverter.cs index 19ae5b9a..652a9bba 100644 --- a/src/Infrastructure.WebApi.Common/JsonDateTimeConverter.cs +++ b/src/Infrastructure.WebApi.Common/JsonDateTimeConverter.cs @@ -66,6 +66,9 @@ private static void WriteIso8601(Utf8JsonWriter writer, DateTime value) } } +/// +/// Defines the formats for JSON timestamps +/// public enum DateFormat { UnixTimestamp, diff --git a/src/Infrastructure.WebApi.Common/XmlHttpResult.cs b/src/Infrastructure.WebApi.Common/XmlHttpResult.cs index 7ede0d9a..4fc3a20c 100644 --- a/src/Infrastructure.WebApi.Common/XmlHttpResult.cs +++ b/src/Infrastructure.WebApi.Common/XmlHttpResult.cs @@ -280,11 +280,17 @@ public static async Task SerializeAsync(Stream responseBody, object? value, Type } } +/// +/// Defines the options for the +/// public class XmlSerializerOptions { public bool WriteIndented { get; set; } } +/// +/// Defines the configurable options for XML serialization +/// public class XmlOptions { public static readonly XmlSerializerOptions DefaultSerializerOptions = new() diff --git a/src/Infrastructure.WebApi.Interfaces/EmptyResponse.cs b/src/Infrastructure.WebApi.Interfaces/EmptyResponse.cs index b74448d4..58664651 100644 --- a/src/Infrastructure.WebApi.Interfaces/EmptyResponse.cs +++ b/src/Infrastructure.WebApi.Interfaces/EmptyResponse.cs @@ -2,6 +2,9 @@ namespace Infrastructure.WebApi.Interfaces; +/// +/// Defines an empty response, for use in empty responses +/// [UsedImplicitly] public class EmptyResponse : IWebResponse { diff --git a/src/Infrastructure.WebApi.Interfaces/HttpError.cs b/src/Infrastructure.WebApi.Interfaces/HttpError.cs index 4e1cf88b..7b2fefa2 100644 --- a/src/Infrastructure.WebApi.Interfaces/HttpError.cs +++ b/src/Infrastructure.WebApi.Interfaces/HttpError.cs @@ -1,5 +1,11 @@ +using System.Net; +using Common; + namespace Infrastructure.WebApi.Interfaces; +/// +/// Defines an error for using in return types +/// public struct HttpError { public HttpError(HttpErrorCode code, string? message) @@ -13,14 +19,17 @@ public HttpError(HttpErrorCode code, string? message) public string? Message { get; } } +/// +/// Defines the commonly used HTTP StatusCodes +/// public enum HttpErrorCode { - BadRequest = 400, - Unauthorized = 401, - PaymentRequired = 402, - Forbidden = 403, - NotFound = 404, - MethodNotAllowed = 405, - Conflict = 409, - InternalServerError = 500 + BadRequest = HttpStatusCode.BadRequest, + Unauthorized = HttpStatusCode.Unauthorized, + PaymentRequired = HttpStatusCode.PaymentRequired, + Forbidden = HttpStatusCode.Forbidden, + NotFound = HttpStatusCode.NotFound, + MethodNotAllowed = HttpStatusCode.MethodNotAllowed, + Conflict = HttpStatusCode.Conflict, + InternalServerError = HttpStatusCode.InternalServerError } \ No newline at end of file diff --git a/src/Infrastructure.WebApi.Interfaces/IWebSearchRequest.cs b/src/Infrastructure.WebApi.Interfaces/IWebSearchRequest.cs index aa106781..573858bc 100644 --- a/src/Infrastructure.WebApi.Interfaces/IWebSearchRequest.cs +++ b/src/Infrastructure.WebApi.Interfaces/IWebSearchRequest.cs @@ -1,5 +1,8 @@ namespace Infrastructure.WebApi.Interfaces; +/// +/// Defines the request of a SEARCH API +/// public interface IWebSearchRequest : IWebRequest, IHasSearchOptions where TResponse : IWebResponse { diff --git a/src/Infrastructure.WebApi.Interfaces/IWebSearchResponse.cs b/src/Infrastructure.WebApi.Interfaces/IWebSearchResponse.cs index 37ac8733..4af5f9a6 100644 --- a/src/Infrastructure.WebApi.Interfaces/IWebSearchResponse.cs +++ b/src/Infrastructure.WebApi.Interfaces/IWebSearchResponse.cs @@ -2,6 +2,9 @@ namespace Infrastructure.WebApi.Interfaces; +/// +/// Defines a response from a SEARCH API +/// public interface IWebSearchResponse : IWebResponse { SearchResultMetadata? Metadata { get; set; } diff --git a/src/Infrastructure.WebApi.Interfaces/SearchRequest.cs b/src/Infrastructure.WebApi.Interfaces/SearchRequest.cs index c2ca02f8..d870480f 100644 --- a/src/Infrastructure.WebApi.Interfaces/SearchRequest.cs +++ b/src/Infrastructure.WebApi.Interfaces/SearchRequest.cs @@ -1,5 +1,8 @@ namespace Infrastructure.WebApi.Interfaces; +/// +/// Defines the request of a SEARCH API +/// public class SearchRequest : IWebSearchRequest where TResponse : IWebResponse { diff --git a/src/Infrastructure.WebApi.Interfaces/SearchResponse.cs b/src/Infrastructure.WebApi.Interfaces/SearchResponse.cs index 35619b96..97eac871 100644 --- a/src/Infrastructure.WebApi.Interfaces/SearchResponse.cs +++ b/src/Infrastructure.WebApi.Interfaces/SearchResponse.cs @@ -2,6 +2,9 @@ namespace Infrastructure.WebApi.Interfaces; +/// +/// Defines a response from a SEARCH API +/// public class SearchResponse : IWebSearchResponse { public SearchResultMetadata? Metadata { get; set; } diff --git a/src/Tools.Analyzers.Core/MissingDocsAnalyzer.cs b/src/Tools.Analyzers.Core/MissingDocsAnalyzer.cs index e230b167..d88b8633 100644 --- a/src/Tools.Analyzers.Core/MissingDocsAnalyzer.cs +++ b/src/Tools.Analyzers.Core/MissingDocsAnalyzer.cs @@ -284,6 +284,7 @@ private static bool IsNotPublicOrInternalStaticMethod(MethodDeclarationSyntax me return false; } + // ReSharper disable once UnusedMember.Local private static bool IsPublicOrInternalExtensionMethod(MethodDeclarationSyntax methodDeclarationSyntax) { var isNotPublicOrInternal = IsNotPublicOrInternalStaticMethod(methodDeclarationSyntax);