Fixed up all missing code documentation

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.
 

src/Application.Common/Caller.cs

@@ -74,6 +74,9 @@ public static ICallerContext CreateAsServiceClient()
         return new ServiceClientAccountCaller();
     }
 
+    /// <summary>
+    ///     Returns a newly generated ID for the call
+    /// </summary>
     public static string GenerateCallId()
     {
         return $"{Guid.NewGuid():N}";

src/Application.Interfaces/GetOptions.cs

@@ -3,6 +3,9 @@
 
 namespace Application.Interfaces;
 
+/// <summary>
+///     Defines options for embedding resources in GET REST API calls
+/// </summary>
 public class GetOptions
 {
     public const string EmbedRequestParamDelimiter = ",";
@@ -50,6 +53,9 @@ public static GetOptions Custom<TResource>(params Expression<Func<TResource, obj
     }
 }
 
+/// <summary>
+///     Defines the options for expanding child resources in REST responses
+/// </summary>
 public enum ExpandOptions
 {
     None = 0,

src/Application.Interfaces/GetOptionsExtensions.cs

@@ -6,6 +6,9 @@ namespace Application.Interfaces;
 
 public static class GetOptionsExtensions
 {
+    /// <summary>
+    ///     Converts the <see cref="propertyReferences" /> expressions to names of the properties
+    /// </summary>
     internal static List<string> ReferencesToNames<TResource>(
         this Expression<Func<TResource, object?>>[] propertyReferences)
     {

src/Application.Interfaces/SearchOptions.cs

@@ -160,12 +160,18 @@ public Sorting(string by, SortDirection direction = SortDirection.Ascending)
 
     public SortDirection Direction { get; }
 
+    /// <summary>
+    ///     Creates a new <see cref="Sorting" /> for the <see cref="field" /> and <see cref="direction" />
+    /// </summary>
     public static Sorting ByField(string field, SortDirection direction = SortDirection.Ascending)
     {
         return new Sorting(field, direction);
     }
 }
 
+/// <summary>
+///     Defines the sorting direction
+/// </summary>
 public enum SortDirection
 {
     Ascending = 0,

src/Common/Error.cs

@@ -15,51 +15,81 @@ private Error(ErrorCode code, string? message = null)
 
     public ErrorCode Code { get; }
 
+    /// <summary>
+    ///     Creates a <see cref="ErrorCode.Validation" /> error
+    /// </summary>
     public static Error Validation(string? message = null)
     {
         return new Error(ErrorCode.Validation, message);
     }
 
+    /// <summary>
+    ///     Creates a <see cref="ErrorCode.RuleViolation" /> error
+    /// </summary>
     public static Error RuleViolation(string? message = null)
     {
         return new Error(ErrorCode.RuleViolation, message);
     }
 
+    /// <summary>
+    ///     Creates a <see cref="ErrorCode.RoleViolation" /> error
+    /// </summary>
     public static Error RoleViolation(string? message = null)
     {
         return new Error(ErrorCode.RoleViolation, message);
     }
 
+    /// <summary>
+    ///     Creates a <see cref="ErrorCode.PreconditionViolation" /> error
+    /// </summary>
     public static Error PreconditionViolation(string? message = null)
     {
         return new Error(ErrorCode.PreconditionViolation, message);
     }
 
+    /// <summary>
+    ///     Creates a <see cref="ErrorCode.EntityNotFound" /> error
+    /// </summary>
     public static Error EntityNotFound(string? message = null)
     {
         return new Error(ErrorCode.EntityNotFound, message);
     }
 
+    /// <summary>
+    ///     Creates a <see cref="ErrorCode.EntityExists" /> error
+    /// </summary>
     public static Error EntityExists(string? message = null)
     {
         return new Error(ErrorCode.EntityExists, message);
     }
 
+    /// <summary>
+    ///     Creates a <see cref="ErrorCode.NotAuthenticated" /> error
+    /// </summary>
     public static Error NotAuthenticated(string? message = null)
     {
         return new Error(ErrorCode.NotAuthenticated, message);
     }
 
+    /// <summary>
+    ///     Creates a <see cref="ErrorCode.ForbiddenAccess" /> error
+    /// </summary>
     public static Error ForbiddenAccess(string? message = null)
     {
         return new Error(ErrorCode.ForbiddenAccess, message);
     }
 
+    /// <summary>
+    ///     Creates a <see cref="ErrorCode.NotSubscribed" /> error
+    /// </summary>
     public static Error NotSubscribed(string? message = null)
     {
         return new Error(ErrorCode.NotSubscribed, message);
     }
 
+    /// <summary>
+    ///     Creates a <see cref="ErrorCode.Unexpected" /> error
+    /// </summary>
     public static Error Unexpected(string? message = null)
     {
         return new Error(ErrorCode.Unexpected, message);

src/Domain.Common/UserRoles.cs

@@ -26,6 +26,9 @@ public static class UserRoles
 #endif
     };
 
+    /// <summary>
+    ///     Whether the <see cref="role" /> is an assignable role
+    /// </summary>
     public static bool IsUserAssignableRole(string role)
     {
         return UserAssignableRoles.ContainsIgnoreCase(role);

src/Domain.Interfaces/CallerConstants.cs

@@ -27,11 +27,17 @@ public const string
         ExternalWebhookAccountUserId
     };
 
+    /// <summary>
+    ///     Whether the user is the <see cref="AnonymousUserId" />
+    /// </summary>
     public static bool IsAnonymousUser(string userId)
     {
         return userId == AnonymousUserId;
     }
 
+    /// <summary>
+    ///     Whether the user is one of the <see cref="ServiceAccounts" />
+    /// </summary>
     public static bool IsServiceAccount(string userId)
     {
         return ServiceAccounts.Contains(userId);

src/Infrastructure.WebApi.Common/HasGetOptions.cs

@@ -17,6 +17,9 @@ public class HasGetOptions : IHasGetOptions
 
     public string? Embed { get; set; }
 
+    /// <summary>
+    ///     Converts the <see cref="resourceProperties" /> to a <see cref="HasGetOptions" />
+    /// </summary>
     public static HasGetOptions Custom<TResource>(params Expression<Func<TResource, object?>>[] resourceProperties)
     {
         return GetOptions.Custom(resourceProperties)

src/Infrastructure.WebApi.Common/JsonDateTimeConverter.cs

@@ -66,6 +66,9 @@ private static void WriteIso8601(Utf8JsonWriter writer, DateTime value)
     }
 }
 
+/// <summary>
+///     Defines the formats for JSON timestamps
+/// </summary>
 public enum DateFormat
 {
     UnixTimestamp,

src/Infrastructure.WebApi.Common/XmlHttpResult.cs

@@ -280,11 +280,17 @@ public static async Task SerializeAsync(Stream responseBody, object? value, Type
     }
 }
 
+/// <summary>
+///     Defines the options for the <see cref="System.Xml.Serialization.XmlSerializer" />
+/// </summary>
 public class XmlSerializerOptions
 {
     public bool WriteIndented { get; set; }
 }
 
+/// <summary>
+///     Defines the configurable options for XML serialization
+/// </summary>
 public class XmlOptions
 {
     public static readonly XmlSerializerOptions DefaultSerializerOptions = new()

src/Infrastructure.WebApi.Interfaces/EmptyResponse.cs

@@ -2,6 +2,9 @@
 
 namespace Infrastructure.WebApi.Interfaces;
 
+/// <summary>
+///     Defines an empty response, for use in empty responses
+/// </summary>
 [UsedImplicitly]
 public class EmptyResponse : IWebResponse
 {

src/Infrastructure.WebApi.Interfaces/HttpError.cs

@@ -1,5 +1,11 @@
+using System.Net;
+using Common;
+
 namespace Infrastructure.WebApi.Interfaces;
 
+/// <summary>
+///     Defines an error for using in <see cref="Result{TError}" /> return types
+/// </summary>
 public struct HttpError
 {
     public HttpError(HttpErrorCode code, string? message)
@@ -13,14 +19,17 @@ public HttpError(HttpErrorCode code, string? message)
     public string? Message { get; }
 }
 
+/// <summary>
+///     Defines the commonly used HTTP StatusCodes
+/// </summary>
 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
 }

src/Infrastructure.WebApi.Interfaces/IWebSearchRequest.cs

@@ -1,5 +1,8 @@
 namespace Infrastructure.WebApi.Interfaces;
 
+/// <summary>
+///     Defines the request of a SEARCH API
+/// </summary>
 public interface IWebSearchRequest<TResponse> : IWebRequest<TResponse>, IHasSearchOptions
     where TResponse : IWebResponse
 {

src/Infrastructure.WebApi.Interfaces/IWebSearchResponse.cs

@@ -2,6 +2,9 @@
 
 namespace Infrastructure.WebApi.Interfaces;
 
+/// <summary>
+///     Defines a response from a SEARCH API
+/// </summary>
 public interface IWebSearchResponse : IWebResponse
 {
     SearchResultMetadata? Metadata { get; set; }

src/Infrastructure.WebApi.Interfaces/SearchRequest.cs

@@ -1,5 +1,8 @@
 namespace Infrastructure.WebApi.Interfaces;
 
+/// <summary>
+///     Defines the request of a SEARCH API
+/// </summary>
 public class SearchRequest<TResponse> : IWebSearchRequest<TResponse>
     where TResponse : IWebResponse
 {

src/Infrastructure.WebApi.Interfaces/SearchResponse.cs

@@ -2,6 +2,9 @@
 
 namespace Infrastructure.WebApi.Interfaces;
 
+/// <summary>
+///     Defines a response from a SEARCH API
+/// </summary>
 public class SearchResponse : IWebSearchResponse
 {
     public SearchResultMetadata? Metadata { get; set; }

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);