Fixes to doc-comments to improve layout of generated API documentation (#1902)

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

* Update links

Author: bkoelman

src/Examples/NoEntityFrameworkExample/NullSafeExpressionRewriter.cs

@@ -6,14 +6,13 @@ namespace NoEntityFrameworkExample;
 /// <summary>
 /// Inserts a null check on member dereference and extension method invocation, to prevent a <see cref="NullReferenceException" /> from being thrown when
 /// the expression is compiled and executed.
-/// </summary>
-/// For example,
-/// <code><![CDATA[
+/// <example>
+/// For example, <code><![CDATA[
 /// Database.TodoItems.Where(todoItem => todoItem.Assignee.Id == todoItem.Owner.Id)
-/// ]]> </code>
-/// would throw if the database contains a
-/// TodoItem that doesn't have an assignee.
-/// <example></example>
+/// ]]></code> would throw if the database
+/// contains a TodoItem that doesn't have an assignee.
+/// </example>
+/// </summary>
 public sealed class NullSafeExpressionRewriter : ExpressionVisitor
 {
     private const string MinValueName = nameof(long.MinValue);

src/JsonApiDotNetCore.Annotations/Configuration/ResourceType.cs

@@ -289,7 +289,7 @@ private static IReadOnlySet<AttrAttribute> GetAttributesInTypeOrDerived(Resource
         }
 
         // Hiding base members using the 'new' keyword instead of 'override' (effectively breaking inheritance) is currently not supported.
-        // https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/knowing-when-to-use-override-and-new-keywords
+        // https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/knowing-when-to-use-override-and-new-keywords
         HashSet<AttrAttribute> attributesInDerivedTypes = [];
 
         foreach (AttrAttribute attributeInDerivedType in resourceType.DirectlyDerivedTypes
@@ -330,7 +330,7 @@ private static IReadOnlySet<RelationshipAttribute> GetRelationshipsInTypeOrDeriv
         }
 
         // Hiding base members using the 'new' keyword instead of 'override' (effectively breaking inheritance) is currently not supported.
-        // https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/knowing-when-to-use-override-and-new-keywords
+        // https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/knowing-when-to-use-override-and-new-keywords
         HashSet<RelationshipAttribute> relationshipsInDerivedTypes = [];
 
         foreach (RelationshipAttribute relationshipInDerivedType in resourceType.DirectlyDerivedTypes

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

@@ -8,8 +8,9 @@ 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[
-/// public class User : Identifiable
+/// <example>
+/// <code><![CDATA[
+/// public class User : Identifiable<long>
 /// {
 ///     [Attr(AttrCapabilities.AllowFilter | AttrCapabilities.AllowSort)]
 ///     [NotMapped]
@@ -25,12 +26,13 @@ namespace JsonApiDotNetCore.Resources.Annotations;
 ///     public string Last { get; set; }
 /// }
 /// 
-/// public class Blog : Identifiable
+/// public class Blog : Identifiable<long>
 /// {
 ///     [HasOne]
 ///     public User Author { get; set; }
 /// }
-/// ]]></example>
+/// ]]></code>
+/// </example>
 /// </remarks>
 [PublicAPI]
 [AttributeUsage(AttributeTargets.Property)]

src/JsonApiDotNetCore.Annotations/Resources/Annotations/HasManyAttribute.cs

@@ -11,7 +11,7 @@ namespace JsonApiDotNetCore.Resources.Annotations;
 /// </summary>
 /// <example>
 /// <code><![CDATA[
-/// public class Author : Identifiable
+/// public class Author : Identifiable<long>
 /// {
 ///     [HasMany]
 ///     public ISet<Article> Articles { get; set; }

src/JsonApiDotNetCore.Annotations/Resources/Annotations/HasOneAttribute.cs

@@ -9,7 +9,7 @@ namespace JsonApiDotNetCore.Resources.Annotations;
 /// </summary>
 /// <example>
 /// <code><![CDATA[
-/// public class Article : Identifiable
+/// public class Article : Identifiable<long>
 /// {
 ///     [HasOne]
 ///     public Author Author { get; set; }

src/JsonApiDotNetCore.Annotations/Resources/Annotations/RelationshipAttribute.cs

@@ -25,13 +25,13 @@ public abstract class RelationshipAttribute : ResourceFieldAttribute
     /// </summary>
     /// <example>
     /// <code><![CDATA[
-    /// public class Article : Identifiable
+    /// public class Article : Identifiable<long>
     /// {
     ///     [HasOne] // InverseNavigationProperty: Person.Articles
     ///     public Person Owner { get; set; }
     /// }
     /// 
-    /// public class Person : Identifiable
+    /// public class Person : Identifiable<long>
     /// {
     ///     [HasMany] // InverseNavigationProperty: Article.Owner
     ///     public ICollection<Article> Articles { get; set; }

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/Annotations/DisableQueryStringAttribute.cs

@@ -6,14 +6,16 @@ namespace JsonApiDotNetCore.Controllers.Annotations;
 /// <summary>
 /// Used on an ASP.NET controller class to indicate which query string parameters are blocked.
 /// </summary>
-/// <example><![CDATA[
+/// <example>
+/// <code><![CDATA[
 /// [DisableQueryString(JsonApiQueryStringParameters.Sort | JsonApiQueryStringParameters.Page)]
 /// public class CustomersController : JsonApiController<Customer> { }
-/// ]]></example>
-/// <example><![CDATA[
+/// ]]></code>
+/// <code><![CDATA[
 /// [DisableQueryString("skipCache")]
 /// public class CustomersController : JsonApiController<Customer> { }
-/// ]]></example>
+/// ]]></code>
+/// </example>
 [PublicAPI]
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct)]
 public sealed class DisableQueryStringAttribute : Attribute

src/JsonApiDotNetCore/Controllers/Annotations/DisableRoutingConventionAttribute.cs

@@ -5,10 +5,12 @@ namespace JsonApiDotNetCore.Controllers.Annotations;
 /// <summary>
 /// Used on an ASP.NET controller class to indicate that a custom route is used instead of the built-in routing convention.
 /// </summary>
-/// <example><![CDATA[
+/// <example>
+/// <code><![CDATA[
 /// [DisableRoutingConvention, Route("some/custom/route/to/customers")]
 /// public class CustomersController : JsonApiController<Customer> { }
-/// ]]></example>
+/// ]]></code>
+/// </example>
 [PublicAPI]
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct)]
 public sealed class DisableRoutingConventionAttribute : Attribute;