Fixes to doc-comments to improve layout of generated API documentation

Author: bkoelman

src/JsonApiDotNetCore.Annotations/Resources/Annotations/EagerLoadAttribute.cs

@@ -8,7 +8,8 @@ namespace JsonApiDotNetCore.Resources.Annotations;
 /// </summary>
 /// <remarks>
 /// This is intended for calculated properties that are exposed as JSON:API attributes, which depend on a related entity to always be loaded.
-/// <example><![CDATA[
+/// <example>
+/// <code><![CDATA[
 /// public class User : Identifiable
 /// {
 ///     [Attr(AttrCapabilities.AllowFilter | AttrCapabilities.AllowSort)]
@@ -30,7 +31,8 @@ namespace JsonApiDotNetCore.Resources.Annotations;
 ///     [HasOne]
 ///     public User Author { get; set; }
 /// }
-/// ]]></example>
+/// ]]></code>
+/// </example>
 /// </remarks>
 [PublicAPI]
 [AttributeUsage(AttributeTargets.Property)]

src/JsonApiDotNetCore.Annotations/Resources/RuntimeTypeConverter.cs

@@ -167,12 +167,12 @@ public static bool CanContainNull(Type type)
 
     /// <summary>
     /// Gets the name of a type, including the names of its generic type arguments, without any namespaces.
-    /// <example>
-    /// <code><![CDATA[
+    /// </summary>
+    /// <returns>
+    /// Example return value: <code><![CDATA[
     /// KeyValuePair<TimeSpan, Nullable<DateTimeOffset>>
     /// ]]></code>
-    /// </example>
-    /// </summary>
+    /// </returns>
     public static string GetFriendlyTypeName(Type type)
     {
         ArgumentNullException.ThrowIfNull(type);

src/JsonApiDotNetCore/Configuration/IJsonApiOptions.cs

@@ -191,7 +191,7 @@ public interface IJsonApiOptions
     /// Enables to customize the settings that are used by the <see cref="JsonSerializer" />.
     /// </summary>
     /// <example>
-    /// The next example sets the naming convention to camel casing.
+    /// The following example sets the naming convention to camel casing.
     /// <code><![CDATA[
     /// options.SerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
     /// options.SerializerOptions.DictionaryKeyPolicy = JsonNamingPolicy.CamelCase;

src/JsonApiDotNetCore/Controllers/BaseJsonApiController.cs

@@ -86,7 +86,7 @@ protected BaseJsonApiController(IJsonApiOptions options, IResourceGraph resource
     }
 
     /// <summary>
-    /// Gets a collection of primary resources. Example: <code><![CDATA[
+    /// Gets a collection of primary resources. Example request: <code language="http"><![CDATA[
     /// GET /articles HTTP/1.1
     /// ]]></code>
     /// </summary>
@@ -105,7 +105,7 @@ public virtual async Task<IActionResult> GetAsync(CancellationToken cancellation
     }
 
     /// <summary>
-    /// Gets a single primary resource by ID. Example: <code><![CDATA[
+    /// Gets a single primary resource by ID. Example request: <code language="http"><![CDATA[
     /// GET /articles/1 HTTP/1.1
     /// ]]></code>
     /// </summary>
@@ -127,10 +127,11 @@ public virtual async Task<IActionResult> GetAsync([DisallowNull] TId id, Cancell
     }
 
     /// <summary>
-    /// Gets a secondary resource or collection of secondary resources. Example: <code><![CDATA[
+    /// Gets a secondary resource or collection of secondary resources. Example request:
+    /// <code language="http"><![CDATA[
     /// GET /articles/1/author HTTP/1.1
-    /// ]]></code> Example:
-    /// <code><![CDATA[
+    /// ]]></code> Example request:
+    /// <code language="http"><![CDATA[
     /// GET /articles/1/revisions HTTP/1.1
     /// ]]></code>
     /// </summary>
@@ -156,11 +157,11 @@ 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. Example:
-    /// <code><![CDATA[
+    /// Gets a relationship value, which can be a <c>null</c>, a single object or a collection. Example request:
+    /// <code language="http"><![CDATA[
     /// GET /articles/1/relationships/author HTTP/1.1
-    /// ]]></code> Example:
-    /// <code><![CDATA[
+    /// ]]></code> Example request:
+    /// <code language="http"><![CDATA[
     /// GET /articles/1/relationships/revisions HTTP/1.1
     /// ]]></code>
     /// </summary>
@@ -186,7 +187,7 @@ public virtual async Task<IActionResult> GetRelationshipAsync([DisallowNull] TId
     }
 
     /// <summary>
-    /// Creates a new resource with attributes, relationships or both. Example: <code><![CDATA[
+    /// Creates a new resource with attributes, relationships or both. Example request: <code language="http"><![CDATA[
     /// POST /articles HTTP/1.1
     /// ]]></code>
     /// </summary>
@@ -233,7 +234,7 @@ private string GetLocationUrl(string resourceId)
     }
 
     /// <summary>
-    /// Adds resources to a to-many relationship. Example: <code><![CDATA[
+    /// Adds resources to a to-many relationship. Example request: <code language="http"><![CDATA[
     /// POST /articles/1/revisions HTTP/1.1
     /// ]]></code>
     /// </summary>
@@ -274,7 +275,7 @@ public virtual async Task<IActionResult> PostRelationshipAsync([DisallowNull] TI
 
     /// <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: <code><![CDATA[
+    /// relationships are replaced. Example request: <code language="http"><![CDATA[
     /// PATCH /articles/1 HTTP/1.1
     /// ]]></code>
     /// </summary>
@@ -304,11 +305,11 @@ public virtual async Task<IActionResult> PatchAsync([DisallowNull] TId id, [From
     }
 
     /// <summary>
-    /// Performs a complete replacement of a relationship on an existing resource. Example:
-    /// <code><![CDATA[
+    /// Performs a complete replacement of a relationship on an existing resource. Example request:
+    /// <code language="http"><![CDATA[
     /// PATCH /articles/1/relationships/author HTTP/1.1
-    /// ]]></code> Example:
-    /// <code><![CDATA[
+    /// ]]></code> Example request:
+    /// <code language="http"><![CDATA[
     /// PATCH /articles/1/relationships/revisions HTTP/1.1
     /// ]]></code>
     /// </summary>
@@ -347,7 +348,7 @@ public virtual async Task<IActionResult> PatchRelationshipAsync([DisallowNull] T
     }
 
     /// <summary>
-    /// Deletes an existing resource. Example: <code><![CDATA[
+    /// Deletes an existing resource. Example request: <code language="http"><![CDATA[
     /// DELETE /articles/1 HTTP/1.1
     /// ]]></code>
     /// </summary>
@@ -369,7 +370,8 @@ public virtual async Task<IActionResult> DeleteAsync([DisallowNull] TId id, Canc
     }
 
     /// <summary>
-    /// Removes resources from a to-many relationship. Example: <code><![CDATA[
+    /// Removes resources from a to-many relationship. Example request:
+    /// <code language="http"><![CDATA[
     /// DELETE /articles/1/relationships/revisions HTTP/1.1
     /// ]]></code>
     /// </summary>

src/JsonApiDotNetCore/Controllers/BaseJsonApiOperationsController.cs

@@ -52,8 +52,8 @@ protected BaseJsonApiOperationsController(IJsonApiOptions options, IResourceGrap
     /// none of the operations returns any data, then HTTP 201 is returned instead of 200.
     /// </summary>
     /// <example>
-    /// The next example creates a new resource.
-    /// <code><![CDATA[
+    /// The following example creates a new resource.
+    /// <code language="http"><![CDATA[
     /// POST /operations HTTP/1.1
     /// Content-Type: application/vnd.api+json;ext="https://jsonapi.org/ext/atomic"
     /// 
@@ -71,8 +71,8 @@ protected BaseJsonApiOperationsController(IJsonApiOptions options, IResourceGrap
     /// ]]></code>
     /// </example>
     /// <example>
-    /// The next example updates an existing resource.
-    /// <code><![CDATA[
+    /// The following example updates an existing resource.
+    /// <code language="http"><![CDATA[
     /// POST /operations HTTP/1.1
     /// Content-Type: application/vnd.api+json;ext="https://jsonapi.org/ext/atomic"
     /// 
@@ -91,8 +91,8 @@ protected BaseJsonApiOperationsController(IJsonApiOptions options, IResourceGrap
     /// ]]></code>
     /// </example>
     /// <example>
-    /// The next example deletes an existing resource.
-    /// <code><![CDATA[
+    /// The following example deletes an existing resource.
+    /// <code language="http"><![CDATA[
     /// POST /operations HTTP/1.1
     /// Content-Type: application/vnd.api+json;ext="https://jsonapi.org/ext/atomic"
     ///