Document JsonApiEndpoints enum

Author: bkoelman

src/JsonApiDotNetCore.Annotations/Controllers/JsonApiEndpoints.shared.cs

@@ -2,25 +2,142 @@
 
 namespace JsonApiDotNetCore.Controllers;
 
-// IMPORTANT: An internal copy of this type exists in the SourceGenerators project. Keep these in sync when making changes.
+/// <summary>
+/// Lists the built-in JSON:API endpoints, described at https://jsonapi.org/format.
+/// </summary>
 [PublicAPI]
 [Flags]
 public enum JsonApiEndpoints
 {
+    // IMPORTANT: An internal copy of this type exists in the JsonApiDotNetCore.SourceGenerators project.
+    // Keep them in sync when making changes.
+
+    /// <summary>
+    /// Represents none of the JSON:API endpoints.
+    /// </summary>
     None = 0,
+
+    /// <summary>
+    /// Represents the endpoint to get a collection of primary resources.
+    /// <para>
+    /// Example endpoint: <code language="http"><![CDATA[
+    /// GET /articles HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     GetCollection = 1,
+
+    /// <summary>
+    /// Represents the endpoint to get a single primary resource by ID.
+    /// <para>
+    /// Example endpoint: <code language="http"><![CDATA[
+    /// GET /articles/1 HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     GetSingle = 1 << 1,
+
+    /// <summary>
+    /// Represents the endpoint to get a secondary resource or collection of secondary resources.
+    /// <para>
+    /// Example endpoints: <code language="http"><![CDATA[
+    /// GET /articles/1/author HTTP/1.1
+    /// ]]></code>
+    /// <code language="http"><![CDATA[
+    /// GET /articles/1/revisions HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     GetSecondary = 1 << 2,
+
+    /// <summary>
+    /// Represents the endpoint to get a relationship value.
+    /// <para>
+    /// Example endpoints: <code language="http"><![CDATA[
+    /// GET /articles/1/relationships/author HTTP/1.1
+    /// ]]></code>
+    /// <code language="http"><![CDATA[
+    /// GET /articles/1/relationships/revisions HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     GetRelationship = 1 << 3,
+
+    /// <summary>
+    /// Represents the endpoint to create a new resource with attributes, relationships, or both.
+    /// <para>
+    /// Example endpoint: <code language="http"><![CDATA[
+    /// POST /articles HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     Post = 1 << 4,
+
+    /// <summary>
+    /// Represents the endpoint to add resources to a to-many relationship.
+    /// <para>
+    /// Example endpoint: <code language="http"><![CDATA[
+    /// POST /articles/1/revisions HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     PostRelationship = 1 << 5,
+
+    /// <summary>
+    /// Represents the endpoint to update the attributes and/or relationships of an existing resource.
+    /// <para>
+    /// Example endpoint: <code language="http"><![CDATA[
+    /// PATCH /articles/1 HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     Patch = 1 << 6,
+
+    /// <summary>
+    /// Represents the endpoint to perform a complete replacement of a relationship on an existing resource.
+    /// <para>
+    /// Example endpoints: <code language="http"><![CDATA[
+    /// PATCH /articles/1/relationships/author HTTP/1.1
+    /// ]]></code>
+    /// <code language="http"><![CDATA[
+    /// PATCH /articles/1/relationships/revisions HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     PatchRelationship = 1 << 7,
+
+    /// <summary>
+    /// Represents the endpoint to delete an existing resource.
+    /// <para>
+    /// Example endpoint: <code language="http"><![CDATA[
+    /// DELETE /articles/1 HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     Delete = 1 << 8,
+
+    /// <summary>
+    /// Represents the endpoint to remove resources from a to-many relationship.
+    /// <para>
+    /// Example endpoint: <code language="http"><![CDATA[
+    /// DELETE /articles/1/relationships/revisions HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     DeleteRelationship = 1 << 9,
 
+    /// <summary>
+    /// Represents the set of JSON:API endpoints to query resources and relationships.
+    /// </summary>
     Query = GetCollection | GetSingle | GetSecondary | GetRelationship,
+
+    /// <summary>
+    /// Represents the set of JSON:API endpoints to change resources and relationships.
+    /// </summary>
     Command = Post | PostRelationship | Patch | PatchRelationship | Delete | DeleteRelationship,
 
+    /// <summary>
+    /// Represents all JSON:API endpoints.
+    /// </summary>
     All = Query | Command
 }

src/JsonApiDotNetCore.SourceGenerators/JsonApiEndpointsCopy.cs

@@ -2,25 +2,142 @@
 
 namespace JsonApiDotNetCore.SourceGenerators;
 
-// IMPORTANT: A copy of this type exists in the JsonApiDotNetCore project. Keep these in sync when making changes.
+/// <summary>
+/// Lists the built-in JSON:API endpoints, described at https://jsonapi.org/format.
+/// </summary>
 [PublicAPI]
 [Flags]
 public enum JsonApiEndpointsCopy
 {
+    // IMPORTANT: A copy of this type exists in the JsonApiDotNetCore.Annotations project.
+    // Keep them in sync when making changes.
+
+    /// <summary>
+    /// Represents none of the JSON:API endpoints.
+    /// </summary>
     None = 0,
+
+    /// <summary>
+    /// Represents the endpoint to get a collection of primary resources.
+    /// <para>
+    /// Example endpoint: <code language="http"><![CDATA[
+    /// GET /articles HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     GetCollection = 1,
+
+    /// <summary>
+    /// Represents the endpoint to get a single primary resource by ID.
+    /// <para>
+    /// Example endpoint: <code language="http"><![CDATA[
+    /// GET /articles/1 HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     GetSingle = 1 << 1,
+
+    /// <summary>
+    /// Represents the endpoint to get a secondary resource or collection of secondary resources.
+    /// <para>
+    /// Example endpoints: <code language="http"><![CDATA[
+    /// GET /articles/1/author HTTP/1.1
+    /// ]]></code>
+    /// <code language="http"><![CDATA[
+    /// GET /articles/1/revisions HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     GetSecondary = 1 << 2,
+
+    /// <summary>
+    /// Represents the endpoint to get a relationship value.
+    /// <para>
+    /// Example endpoints: <code language="http"><![CDATA[
+    /// GET /articles/1/relationships/author HTTP/1.1
+    /// ]]></code>
+    /// <code language="http"><![CDATA[
+    /// GET /articles/1/relationships/revisions HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     GetRelationship = 1 << 3,
+
+    /// <summary>
+    /// Represents the endpoint to create a new resource with attributes, relationships, or both.
+    /// <para>
+    /// Example endpoint: <code language="http"><![CDATA[
+    /// POST /articles HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     Post = 1 << 4,
+
+    /// <summary>
+    /// Represents the endpoint to add resources to a to-many relationship.
+    /// <para>
+    /// Example endpoint: <code language="http"><![CDATA[
+    /// POST /articles/1/revisions HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     PostRelationship = 1 << 5,
+
+    /// <summary>
+    /// Represents the endpoint to update the attributes and/or relationships of an existing resource.
+    /// <para>
+    /// Example endpoint: <code language="http"><![CDATA[
+    /// PATCH /articles/1 HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     Patch = 1 << 6,
+
+    /// <summary>
+    /// Represents the endpoint to perform a complete replacement of a relationship on an existing resource.
+    /// <para>
+    /// Example endpoints: <code language="http"><![CDATA[
+    /// PATCH /articles/1/relationships/author HTTP/1.1
+    /// ]]></code>
+    /// <code language="http"><![CDATA[
+    /// PATCH /articles/1/relationships/revisions HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     PatchRelationship = 1 << 7,
+
+    /// <summary>
+    /// Represents the endpoint to delete an existing resource.
+    /// <para>
+    /// Example endpoint: <code language="http"><![CDATA[
+    /// DELETE /articles/1 HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     Delete = 1 << 8,
+
+    /// <summary>
+    /// Represents the endpoint to remove resources from a to-many relationship.
+    /// <para>
+    /// Example endpoint: <code language="http"><![CDATA[
+    /// DELETE /articles/1/relationships/revisions HTTP/1.1
+    /// ]]></code>
+    /// </para>
+    /// </summary>
     DeleteRelationship = 1 << 9,
 
+    /// <summary>
+    /// Represents the set of JSON:API endpoints to query resources and relationships.
+    /// </summary>
     Query = GetCollection | GetSingle | GetSecondary | GetRelationship,
+
+    /// <summary>
+    /// Represents the set of JSON:API endpoints to change resources and relationships.
+    /// </summary>
     Command = Post | PostRelationship | Patch | PatchRelationship | Delete | DeleteRelationship,
 
+    /// <summary>
+    /// Represents all JSON:API endpoints.
+    /// </summary>
     All = Query | Command
 }

src/JsonApiDotNetCore/AtomicOperations/Processors/ICreateProcessor.cs

@@ -6,7 +6,7 @@
 namespace JsonApiDotNetCore.AtomicOperations.Processors;
 
 /// <summary>
-/// Processes a single operation to create a new resource with attributes, relationships or both.
+/// Processes a single operation to create a new resource with attributes, relationships, or both.
 /// </summary>
 /// <typeparam name="TResource">
 /// The resource type.

src/JsonApiDotNetCore/Controllers/BaseJsonApiController.cs

@@ -165,7 +165,7 @@ public virtual async Task<IActionResult> GetSecondaryAsync([DisallowNull] TId id
     }
 
     /// <summary>
-    /// Gets a relationship value, which can be a <c>null</c>, a single object or a collection.
+    /// Gets a relationship value, which can be <c>null</c>, a single object or a collection.
     /// <para>
     /// Example endpoints: <code language="http"><![CDATA[
     /// GET /articles/1/relationships/author HTTP/1.1
@@ -197,7 +197,7 @@ public virtual async Task<IActionResult> GetRelationshipAsync([DisallowNull] TId
     }
 
     /// <summary>
-    /// Creates a new resource with attributes, relationships or both.
+    /// Creates a new resource with attributes, relationships, or both.
     /// <para>
     /// Example endpoint: <code language="http"><![CDATA[
     /// POST /articles HTTP/1.1

src/JsonApiDotNetCore/Middleware/WriteOperationKind.cs

@@ -7,7 +7,7 @@ namespace JsonApiDotNetCore.Middleware;
 public enum WriteOperationKind
 {
     /// <summary>
-    /// Create a new resource with attributes, relationships or both.
+    /// Create a new resource with attributes, relationships, or both.
     /// </summary>
     CreateResource,
 

src/JsonApiDotNetCore/Services/ICreateService.cs

@@ -7,7 +7,7 @@ public interface ICreateService<TResource, in TId>
     where TResource : class, IIdentifiable<TId>
 {
     /// <summary>
-    /// Handles a JSON:API request to create a new resource with attributes, relationships or both.
+    /// Handles a JSON:API request to create a new resource with attributes, relationships, or both.
     /// </summary>
     Task<TResource?> CreateAsync(TResource resource, CancellationToken cancellationToken);
 }