Clarifications in doc-comments

Author: Bart Koelman

src/JsonApiDotNetCore/Controllers/BaseJsonApiController.cs

@@ -87,7 +87,9 @@ protected BaseJsonApiController(IJsonApiOptions options, IResourceGraph resource
         }
 
         /// <summary>
-        /// Gets a collection of top-level (non-nested) resources. Example: GET /articles HTTP/1.1
+        /// Gets a collection of primary resources. Example: <code><![CDATA[
+        /// GET /articles HTTP/1.1
+        /// ]]></code>
         /// </summary>
         public virtual async Task<IActionResult> GetAsync(CancellationToken cancellationToken)
         {
@@ -104,7 +106,9 @@ public virtual async Task<IActionResult> GetAsync(CancellationToken cancellation
         }
 
         /// <summary>
-        /// Gets a single top-level (non-nested) resource by ID. Example: /articles/1
+        /// Gets a single primary resource by ID. Example: <code><![CDATA[
+        /// GET /articles/1 HTTP/1.1
+        /// ]]></code>
         /// </summary>
         public virtual async Task<IActionResult> GetAsync(TId id, CancellationToken cancellationToken)
         {
@@ -124,7 +128,12 @@ public virtual async Task<IActionResult> GetAsync(TId id, CancellationToken canc
         }
 
         /// <summary>
-        /// Gets a single resource or multiple resources at a nested endpoint. Examples: GET /articles/1/author HTTP/1.1 GET /articles/1/revisions HTTP/1.1
+        /// Gets 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>
         public virtual async Task<IActionResult> GetSecondaryAsync(TId id, string relationshipName, CancellationToken cancellationToken)
         {
@@ -147,7 +156,13 @@ public virtual async Task<IActionResult> GetSecondaryAsync(TId id, string relati
         }
 
         /// <summary>
-        /// Gets a single resource relationship. Example: GET /articles/1/relationships/author HTTP/1.1 Example: GET /articles/1/relationships/revisions HTTP/1.1
+        /// Gets a relationship value, which can be a <c>null</c>, a single object or a collection. 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>
         public virtual async Task<IActionResult> GetRelationshipAsync(TId id, string relationshipName, CancellationToken cancellationToken)
         {
@@ -170,7 +185,9 @@ public virtual async Task<IActionResult> GetRelationshipAsync(TId id, string rel
         }
 
         /// <summary>
-        /// Creates a new resource with attributes, relationships or both. Example: POST /articles HTTP/1.1
+        /// Creates a new resource with attributes, relationships or both. Example: <code><![CDATA[
+        /// POST /articles HTTP/1.1
+        /// ]]></code>
         /// </summary>
         public virtual async Task<IActionResult> PostAsync([FromBody] TResource resource, CancellationToken cancellationToken)
         {
@@ -206,7 +223,9 @@ public virtual async Task<IActionResult> PostAsync([FromBody] TResource resource
         }
 
         /// <summary>
-        /// Adds resources to a to-many relationship. Example: POST /articles/1/revisions HTTP/1.1
+        /// Adds resources to a to-many relationship. Example: <code><![CDATA[
+        /// POST /articles/1/revisions HTTP/1.1
+        /// ]]></code>
         /// </summary>
         /// <param name="id">
         /// Identifies the left side of the relationship.
@@ -245,7 +264,9 @@ public virtual async Task<IActionResult> PostRelationshipAsync(TId id, string re
 
         /// <summary>
         /// Updates the attributes and/or relationships of an existing resource. Only the values of sent attributes are replaced. And only the values of sent
-        /// relationships are replaced. Example: PATCH /articles/1 HTTP/1.1
+        /// relationships are replaced. Example: <code><![CDATA[
+        /// PATCH /articles/1 HTTP/1.1
+        /// ]]></code>
         /// </summary>
         public virtual async Task<IActionResult> PatchAsync(TId id, [FromBody] TResource resource, CancellationToken cancellationToken)
         {
@@ -268,12 +289,18 @@ public virtual async Task<IActionResult> PatchAsync(TId id, [FromBody] TResource
             }
 
             TResource? updated = await _update.UpdateAsync(id, resource, cancellationToken);
+
             return updated == null ? NoContent() : Ok(updated);
         }
 
         /// <summary>
-        /// Performs a complete replacement of a relationship on an existing resource. Example: PATCH /articles/1/relationships/author HTTP/1.1 Example: PATCH
-        /// /articles/1/relationships/revisions HTTP/1.1
+        /// Performs 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>
         /// <param name="id">
         /// Identifies the left side of the relationship.
@@ -310,7 +337,9 @@ public virtual async Task<IActionResult> PatchRelationshipAsync(TId id, string r
         }
 
         /// <summary>
-        /// Deletes an existing resource. Example: DELETE /articles/1 HTTP/1.1
+        /// Deletes an existing resource. Example: <code><![CDATA[
+        /// DELETE /articles/1 HTTP/1.1
+        /// ]]></code>
         /// </summary>
         public virtual async Task<IActionResult> DeleteAsync(TId id, CancellationToken cancellationToken)
         {
@@ -330,7 +359,9 @@ public virtual async Task<IActionResult> DeleteAsync(TId id, CancellationToken c
         }
 
         /// <summary>
-        /// Removes resources from a to-many relationship. Example: DELETE /articles/1/relationships/revisions HTTP/1.1
+        /// Removes resources from a to-many relationship. Example: <code><![CDATA[
+        /// DELETE /articles/1/relationships/revisions HTTP/1.1
+        /// ]]></code>
         /// </summary>
         /// <param name="id">
         /// Identifies the left side of the relationship.

src/JsonApiDotNetCore/Middleware/IJsonApiRequest.cs

@@ -14,26 +14,26 @@ public interface IJsonApiRequest
         public EndpointKind Kind { get; }
 
         /// <summary>
-        /// The ID of the primary (top-level) resource for this request. This would be null in "/blogs", "123" in "/blogs/123" or "/blogs/123/author". This is
+        /// The ID of the primary resource for this request. This would be <c>null</c> in "/blogs", "123" in "/blogs/123" or "/blogs/123/author". This is
         /// <c>null</c> before and after processing operations in an atomic:operations request.
         /// </summary>
         string? PrimaryId { get; }
 
         /// <summary>
-        /// The primary (top-level) resource type for this request. This would be "blogs" in "/blogs", "/blogs/123" or "/blogs/123/author". This is <c>null</c>
-        /// before and after processing operations in an atomic:operations request.
+        /// The primary resource type for this request. This would be "blogs" in "/blogs", "/blogs/123" or "/blogs/123/author". This is <c>null</c> before and
+        /// after processing operations in an atomic:operations request.
         /// </summary>
         ResourceType? PrimaryResourceType { get; }
 
         /// <summary>
-        /// The secondary (nested) resource type for this request. This would be null in "/blogs", "/blogs/123" and "/blogs/123/unknownResource" or "people" in
+        /// The secondary resource type for this request. This would be <c>null</c> in "/blogs", "/blogs/123" and "/blogs/123/unknownResource" or "people" in
         /// "/blogs/123/author" and "/blogs/123/relationships/author". This is <c>null</c> before and after processing operations in an atomic:operations
         /// request.
         /// </summary>
         ResourceType? SecondaryResourceType { get; }
 
         /// <summary>
-        /// The relationship for this nested request. This would be null in "/blogs", "/blogs/123" and "/blogs/123/unknownResource" or "author" in
+        /// The relationship for this request. This would be <c>null</c> in "/blogs", "/blogs/123" and "/blogs/123/unknownResource" or "author" in
         /// "/blogs/123/author" and "/blogs/123/relationships/author". This is <c>null</c> before and after processing operations in an atomic:operations
         /// request.
         /// </summary>
@@ -45,13 +45,13 @@ public interface IJsonApiRequest
         bool IsCollection { get; }
 
         /// <summary>
-        /// Indicates whether this request targets only fetching of data (such as resources and relationships).
+        /// Indicates whether this request targets only fetching of data (resources and relationships), as opposed to applying changes.
         /// </summary>
         bool IsReadOnly { get; }
 
         /// <summary>
         /// In case of a non-readonly request, this indicates the kind of write operation currently being processed. This is <c>null</c> when processing a
-        /// read-only operations, or before and after processing operations in an atomic:operations request.
+        /// read-only operation, and before and after processing operations in an atomic:operations request.
         /// </summary>
         WriteOperationKind? WriteOperation { get; }
 

test/TestBuildingBlocks/ObjectAssertionsExtensions.cs

@@ -67,7 +67,7 @@ public static AndConstraint<NullableNumericAssertions<decimal>> BeApproximately(
         }
 
         /// <summary>
-        /// Used to assert on a JSON-formatted string, ignoring differences in insignificant whitespace and line endings.
+        /// Asserts that a JSON-formatted string matches the specified expected one, ignoring differences in insignificant whitespace and line endings.
         /// </summary>
         [CustomAssertion]
         public static void BeJson(this StringAssertions source, string expected, string because = "", params object[] becauseArgs)