Merge pull request #298 from json-api-dotnet/docs/xml-documentation

docs(*): add xml comments

Author: jaredcnance

src/JsonApiDotNetCore/Builders/IDocumentBuilderOptionsProvider.cs

@@ -1,11 +1,7 @@
-using System;
-using System.Collections.Generic;
-using System.Text;
-
 namespace JsonApiDotNetCore.Builders
 {
     public interface IDocumentBuilderOptionsProvider
     {
-        DocumentBuilderOptions GetDocumentBuilderOptions(); 
+        DocumentBuilderOptions GetDocumentBuilderOptions();
     }
 }

src/JsonApiDotNetCore/Configuration/NullAttributeResponseBehavior.cs

@@ -1,19 +1,34 @@
-using System;
-using System.Collections.Generic;
-using System.Text;
-
 namespace JsonApiDotNetCore.Configuration
 {
+    /// <summary>
+    /// Allows null attributes to be ommitted from the response payload
+    /// </summary>
     public struct NullAttributeResponseBehavior
     {
+        /// <param name="omitNullValuedAttributes">Do not serialize null attributes</param>
+        /// <param name="allowClientOverride">
+        /// Allow clients to override the serialization behavior through a query parmeter.
+        /// <example>
+        /// ```
+        /// GET /articles?omitNullValuedAttributes=true
+        /// ```
+        /// </example>
+        /// </param>
         public NullAttributeResponseBehavior(bool omitNullValuedAttributes = false, bool allowClientOverride = false)
         {
             OmitNullValuedAttributes = omitNullValuedAttributes;
             AllowClientOverride = allowClientOverride;
         }
 
+        /// <summary>
+        /// Do not include null attributes in the response payload.
+        /// </summary>
         public bool OmitNullValuedAttributes { get; }
+
+        /// <summary>
+        /// Allows clients to specify a `omitNullValuedAttributes` boolean query param to control
+        /// serialization behavior.
+        /// </summary>
         public bool AllowClientOverride { get; }
-        // ...
     }
 }

src/JsonApiDotNetCore/Models/AttrAttribute.cs

@@ -5,6 +5,26 @@ namespace JsonApiDotNetCore.Models
 {
     public class AttrAttribute : Attribute
     {
+        /// <summary>
+        /// Defines a public attribute exposed by the API
+        /// </summary>
+        /// 
+        /// <param name="publicName">How this attribute is exposed through the API</param>
+        /// <param name="isImmutable">Prevent PATCH requests from updating the value</param>
+        /// <param name="isFilterable">Prevent filters on this attribute</param>
+        /// <param name="isSortable">Prevent this attribute from being sorted by</param>
+        /// 
+        /// <example>
+        /// 
+        /// <code>
+        /// public class Author : Identifiable
+        /// {
+        ///     [Attr("name")]
+        ///     public string Name { get; set; }
+        /// }
+        /// </code>
+        /// 
+        /// </example>
         public AttrAttribute(string publicName, bool isImmutable = false, bool isFilterable = true, bool isSortable = true)
         {
             PublicAttributeName = publicName;
@@ -20,20 +40,51 @@ internal AttrAttribute(string publicName, string internalName, bool isImmutable
             IsImmutable = isImmutable;
         }
 
+        /// <summary>
+        /// How this attribute is exposed through the API
+        /// </summary>
         public string PublicAttributeName { get; }
+
+        /// <summary>
+        /// The internal property name this attribute belongs to.
+        /// </summary>
         public string InternalAttributeName { get; internal set; }
+
+        /// <summary>
+        /// Prevents PATCH requests from updating the value.
+        /// </summary>
         public bool IsImmutable { get; }
+
+        /// <summary>
+        /// Whether or not this attribute can be filtered on via a query string filters.
+        /// Attempts to filter on an attribute with `IsFilterable == false` will return
+        /// an HTTP 400 response.
+        /// </summary>
         public bool IsFilterable { get; }
+
+        /// <summary>
+        /// Whether or not this attribute can be sorted on via a query string sort.
+        /// Attempts to filter on an attribute with `IsSortable == false` will return
+        /// an HTTP 400 response.
+        /// </summary>
         public bool IsSortable { get; }
 
+        /// <summary>
+        /// Get the value of the attribute for the given object.
+        /// Returns null if the attribute does not belong to the
+        /// provided object.
+        /// </summary>
         public object GetValue(object entity)
         {
             return entity
                 .GetType()
                 .GetProperty(InternalAttributeName)
-                .GetValue(entity);
+                ?.GetValue(entity);
         }
 
+        /// <summary>
+        /// Sets the value of the attribute on the given object.
+        /// </summary>
         public void SetValue(object entity, object newValue)
         {
             var propertyInfo = entity

src/JsonApiDotNetCore/Models/HasManyAttribute.cs

@@ -2,16 +2,40 @@ namespace JsonApiDotNetCore.Models
 {
     public class HasManyAttribute : RelationshipAttribute
     {
+        /// <summary>
+        /// Create a HasMany relational link to another entity
+        /// </summary>
+        /// 
+        /// <param name="publicName">The relationship name as exposed by the API</param>
+        /// <param name="documentLinks">Which links are available. Defaults to <see cref="Link.All"/></param>
+        /// <param name="canInclude">Whether or not this relationship can be included using the <c>?include=public-name</c> query string</param>
+        /// 
+        /// <example>
+        /// 
+        /// <code>
+        /// public class Author : Identifiable 
+        /// {
+        ///     [HasMany("articles"]
+        ///     public virtual List<Article> Articles { get; set; }
+        /// }
+        /// </code>
+        /// 
+        /// </example>
         public HasManyAttribute(string publicName, Link documentLinks = Link.All, bool canInclude = true)
         : base(publicName, documentLinks, canInclude)
         { }
 
+        /// <summary>
+        /// Sets the value of the property identified by this attribute
+        /// </summary>
+        /// <param name="entity">The target object</param>
+        /// <param name="newValue">The new property value</param>
         public override void SetValue(object entity, object newValue)
         {
             var propertyInfo = entity
                 .GetType()
                 .GetProperty(InternalRelationshipName);
-            
+
             propertyInfo.SetValue(entity, newValue);
         }
     }

src/JsonApiDotNetCore/Services/QueryComposer.cs

@@ -1,6 +1,5 @@
 using System.Collections.Generic;
 using JsonApiDotNetCore.Internal.Query;
-using Microsoft.Extensions.Logging;
 
 namespace JsonApiDotNetCore.Services
 {
@@ -14,8 +13,8 @@ public class QueryComposer : IQueryComposer
         public string Compose(IJsonApiContext jsonApiContext)
         {
             string result = "";
-            if(jsonApiContext != null && jsonApiContext.QuerySet != null)
-            {                
+            if (jsonApiContext != null && jsonApiContext.QuerySet != null)
+            {
                 List<FilterQuery> filterQueries = jsonApiContext.QuerySet.Filters;
                 if (filterQueries.Count > 0)
                 {