From 6802934fddc41df8577419861cc7503530095b34 Mon Sep 17 00:00:00 2001
From: Bart Koelman <10324372+bkoelman@users.noreply.github.com>
Date: Tue, 5 Sep 2023 21:11:18 +0200
Subject: [PATCH] Document JsonApiEndpoints enum

---
 .../Controllers/JsonApiEndpoints.shared.cs    | 86 +++++++++++++++++++
 .../JsonApiEndpointsCopy.cs                   | 86 +++++++++++++++++++
 2 files changed, 172 insertions(+)

diff --git a/src/JsonApiDotNetCore.Annotations/Controllers/JsonApiEndpoints.shared.cs b/src/JsonApiDotNetCore.Annotations/Controllers/JsonApiEndpoints.shared.cs
index a6d11e6093..fe8f360c3e 100644
--- a/src/JsonApiDotNetCore.Annotations/Controllers/JsonApiEndpoints.shared.cs
+++ b/src/JsonApiDotNetCore.Annotations/Controllers/JsonApiEndpoints.shared.cs
@@ -7,20 +7,106 @@ namespace JsonApiDotNetCore.Controllers;
 [Flags]
 public enum JsonApiEndpoints
 {
+    /// <summary>
+    /// Represents none of the JSON:API endpoints.
+    /// </summary>
     None = 0,
+
+    /// <summary>
+    /// Represents the endpoint to get a collection of primary resources. Example: <code><![CDATA[
+    /// GET /articles HTTP/1.1
+    /// ]]></code>
+    /// </summary>
     GetCollection = 1,
+
+    /// <summary>
+    /// Represents the endpoint to get a single primary resource by ID. Example: <code><![CDATA[
+    /// GET /articles/1 HTTP/1.1
+    /// ]]></code>
+    /// </summary>
     GetSingle = 1 << 1,
+
+    /// <summary>
+    /// Represents the endpoint to get a secondary resource or collection of secondary resources. Example:
+    /// <code><![CDATA[
+    /// GET /articles/1/author HTTP/1.1
+    /// ]]></code> Example: <code><![CDATA[
+    /// GET /articles/1/revisions HTTP/1.1
+    /// ]]></code>
+    /// </summary>
     GetSecondary = 1 << 2,
+
+    /// <summary>
+    /// Represents the endpoint to get a relationship value. Example: <code><![CDATA[
+    /// GET /articles/1/relationships/author HTTP/1.1
+    /// ]]></code> Example:
+    /// <code><![CDATA[
+    /// GET /articles/1/relationships/revisions HTTP/1.1
+    /// ]]></code>
+    /// </summary>
     GetRelationship = 1 << 3,
+
+    /// <summary>
+    /// Represents the endpoint to create a new resource with attributes, relationships or both. Example:
+    /// <code><![CDATA[
+    /// POST /articles HTTP/1.1
+    /// ]]></code>
+    /// </summary>
     Post = 1 << 4,
+
+    /// <summary>
+    /// Represents the endpoint to add resources to a to-many relationship. Example: <code><![CDATA[
+    /// POST /articles/1/revisions HTTP/1.1
+    /// ]]></code>
+    /// </summary>
     PostRelationship = 1 << 5,
+
+    /// <summary>
+    /// Represents the endpoint to update the attributes and/or relationships of an existing resource. Example:
+    /// <code><![CDATA[
+    /// PATCH /articles/1
+    /// ]]></code>
+    /// </summary>
     Patch = 1 << 6,
+
+    /// <summary>
+    /// Represents the endpoint to perform a complete replacement of a relationship on an existing resource. Example:
+    /// <code><![CDATA[
+    /// PATCH /articles/1/relationships/author HTTP/1.1
+    /// ]]></code> Example:
+    /// <code><![CDATA[
+    /// PATCH /articles/1/relationships/revisions HTTP/1.1
+    /// ]]></code>
+    /// </summary>
     PatchRelationship = 1 << 7,
+
+    /// <summary>
+    /// Represents the endpoint to delete an existing resource. Example: <code><![CDATA[
+    /// DELETE /articles/1
+    /// ]]></code>
+    /// </summary>
     Delete = 1 << 8,
+
+    /// <summary>
+    /// Represents the endpoint to remove resources from a to-many relationship. Example:
+    /// <code><![CDATA[
+    /// DELETE /articles/1/relationships/revisions
+    /// ]]></code>
+    /// </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 of the JSON:API endpoints.
+    /// </summary>
     All = Query | Command
 }
diff --git a/src/JsonApiDotNetCore.SourceGenerators/JsonApiEndpointsCopy.cs b/src/JsonApiDotNetCore.SourceGenerators/JsonApiEndpointsCopy.cs
index 911be3f359..862892a77f 100644
--- a/src/JsonApiDotNetCore.SourceGenerators/JsonApiEndpointsCopy.cs
+++ b/src/JsonApiDotNetCore.SourceGenerators/JsonApiEndpointsCopy.cs
@@ -4,20 +4,106 @@ namespace JsonApiDotNetCore.SourceGenerators;
 [Flags]
 public enum JsonApiEndpointsCopy
 {
+    /// <summary>
+    /// Represents none of the JSON:API endpoints.
+    /// </summary>
     None = 0,
+
+    /// <summary>
+    /// Represents the endpoint to get a collection of primary resources. Example: <code><![CDATA[
+    /// GET /articles HTTP/1.1
+    /// ]]></code>
+    /// </summary>
     GetCollection = 1,
+
+    /// <summary>
+    /// Represents the endpoint to get a single primary resource by ID. Example: <code><![CDATA[
+    /// GET /articles/1 HTTP/1.1
+    /// ]]></code>
+    /// </summary>
     GetSingle = 1 << 1,
+
+    /// <summary>
+    /// Represents the endpoint to get a secondary resource or collection of secondary resources. Example:
+    /// <code><![CDATA[
+    /// GET /articles/1/author HTTP/1.1
+    /// ]]></code> Example: <code><![CDATA[
+    /// GET /articles/1/revisions HTTP/1.1
+    /// ]]></code>
+    /// </summary>
     GetSecondary = 1 << 2,
+
+    /// <summary>
+    /// Represents the endpoint to get a relationship value. Example: <code><![CDATA[
+    /// GET /articles/1/relationships/author HTTP/1.1
+    /// ]]></code> Example:
+    /// <code><![CDATA[
+    /// GET /articles/1/relationships/revisions HTTP/1.1
+    /// ]]></code>
+    /// </summary>
     GetRelationship = 1 << 3,
+
+    /// <summary>
+    /// Represents the endpoint to create a new resource with attributes, relationships or both. Example:
+    /// <code><![CDATA[
+    /// POST /articles HTTP/1.1
+    /// ]]></code>
+    /// </summary>
     Post = 1 << 4,
+
+    /// <summary>
+    /// Represents the endpoint to add resources to a to-many relationship. Example: <code><![CDATA[
+    /// POST /articles/1/revisions HTTP/1.1
+    /// ]]></code>
+    /// </summary>
     PostRelationship = 1 << 5,
+
+    /// <summary>
+    /// Represents the endpoint to update the attributes and/or relationships of an existing resource. Example:
+    /// <code><![CDATA[
+    /// PATCH /articles/1
+    /// ]]></code>
+    /// </summary>
     Patch = 1 << 6,
+
+    /// <summary>
+    /// Represents the endpoint to perform a complete replacement of a relationship on an existing resource. Example:
+    /// <code><![CDATA[
+    /// PATCH /articles/1/relationships/author HTTP/1.1
+    /// ]]></code> Example:
+    /// <code><![CDATA[
+    /// PATCH /articles/1/relationships/revisions HTTP/1.1
+    /// ]]></code>
+    /// </summary>
     PatchRelationship = 1 << 7,
+
+    /// <summary>
+    /// Represents the endpoint to delete an existing resource. Example: <code><![CDATA[
+    /// DELETE /articles/1
+    /// ]]></code>
+    /// </summary>
     Delete = 1 << 8,
+
+    /// <summary>
+    /// Represents the endpoint to remove resources from a to-many relationship. Example:
+    /// <code><![CDATA[
+    /// DELETE /articles/1/relationships/revisions
+    /// ]]></code>
+    /// </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 of the JSON:API endpoints.
+    /// </summary>
     All = Query | Command
 }