docs: add missing API documentation

Author: jaredcnance

docs/api/index.md

@@ -1,2 +1,10 @@
-# PLACEHOLDER
-TODO: Add .NET projects to the *src* folder and run `docfx` to generate **REAL** *API Documentation*!
+# API
+
+This section documents the package API and is generated from the XML source comments.
+
+## Common APIs
+
+- [`JsonApiOptions`](JsonApiDotNetCore.Configuration.JsonApiOptions.html)
+- [`IResourceGraph`](JsonApiDotNetCore.Internal.IResourceGraph.html)
+- [`ResourceDefinition<T>`](JsonApiDotNetCore.Models.ResourceDefinition-1.html)
+- [`IQueryAccessor`](JsonApiDotNetCore.Services.IQueryAccessor.html)

src/JsonApiDotNetCore/Builders/ContextGraphBuilder.cs

@@ -81,8 +81,10 @@ public class ResourceGraphBuilder : IResourceGraphBuilder
         private bool _usesDbContext;
         private IResourceNameFormatter _resourceNameFormatter = JsonApiOptions.ResourceNameFormatter;
 
+        /// <inheritdoc />
         public Link DocumentLinks { get; set; } = Link.All;
 
+        /// <inheritdoc />
         public IResourceGraph Build()
         {
             // this must be done at build so that call order doesn't matter

src/JsonApiDotNetCore/Builders/DocumentBuilder.cs

@@ -9,6 +9,7 @@
 
 namespace JsonApiDotNetCore.Builders
 {
+    /// <inheritdoc />
     public class DocumentBuilder : IDocumentBuilder
     {
         private readonly IJsonApiContext _jsonApiContext;
@@ -30,6 +31,7 @@ public DocumentBuilder(
             _scopedServiceProvider = scopedServiceProvider;
         }
 
+        /// <inheritdoc />
         public Document Build(IIdentifiable entity)
         {
             var contextEntity = _resourceGraph.GetContextEntity(entity.GetType());
@@ -49,6 +51,7 @@ public Document Build(IIdentifiable entity)
             return document;
         }
 
+        /// <inheritdoc />
         public Documents Build(IEnumerable<IIdentifiable> entities)
         {
             var entityType = entities.GetElementType();
@@ -110,6 +113,7 @@ private List<ResourceObject> AppendIncludedObject(List<ResourceObject> includedO
         public ResourceObject GetData(ContextEntity contextEntity, IIdentifiable entity)
             => GetData(contextEntity, entity, resourceDefinition: null);
 
+        /// <inheritdoc />
         public ResourceObject GetData(ContextEntity contextEntity, IIdentifiable entity, IResourceDefinition resourceDefinition = null)
         {
             var data = new ResourceObject

src/JsonApiDotNetCore/Builders/DocumentBuilderOptions.cs

@@ -1,12 +1,29 @@
 namespace JsonApiDotNetCore.Builders
 {
+    /// <summary>
+    /// Options used to configure how a model gets serialized into
+    /// a json:api document.
+    /// </summary>
     public struct DocumentBuilderOptions
     {
+        /// <param name="omitNullValuedAttributes">
+        /// Do not serialize attributes with null values.
+        /// </param>
         public DocumentBuilderOptions(bool omitNullValuedAttributes = false)
         {
             this.OmitNullValuedAttributes = omitNullValuedAttributes;
         }
 
+        /// <summary>
+        /// Prevent attributes with null values from being included in the response.
+        /// This type is mostly internal and if you want to enable this behavior, you
+        /// should do so on the <see ref="JsonApiDotNetCore.Configuration.JsonApiOptions" />.
+        /// </summary>
+        /// <example>
+        /// <code>
+        /// options.NullAttributeResponseBehavior = new NullAttributeResponseBehavior(true);
+        /// </code>
+        /// </example>
         public bool OmitNullValuedAttributes { get; private set; }
     }
 }

src/JsonApiDotNetCore/Builders/IDocumentBuilder.cs

@@ -7,11 +7,31 @@ namespace JsonApiDotNetCore.Builders
 {
     public interface IDocumentBuilder
     {
+        /// <summary>
+        /// Builds a json:api document from the provided resource instance.
+        /// </summary>
+        /// <param name="entity">The resource to convert.</param>
         Document Build(IIdentifiable entity);
+
+        /// <summary>
+        /// Builds a json:api document from the provided resource instances.
+        /// </summary>
+        /// <param name="entities">The collection of resources to convert.</param>
         Documents Build(IEnumerable<IIdentifiable> entities);
 
         [Obsolete("You should specify an IResourceDefinition implementation using the GetData/3 overload.")]
         ResourceObject GetData(ContextEntity contextEntity, IIdentifiable entity);
+
+        /// <summary>
+        /// Create the resource object for the provided resource.
+        /// </summary>
+        /// <param name="contextEntity">The metadata for the resource.</param>
+        /// <param name="entity">The resource instance.</param>
+        /// <param name="resourceDefinition">
+        /// The resource definition (optional). This can be used for filtering out attributes
+        /// that should not be exposed to the client. For example, you might want to limit
+        /// the exposed attributes based on the authenticated user's role.
+        /// </param>
         ResourceObject GetData(ContextEntity contextEntity, IIdentifiable entity, IResourceDefinition resourceDefinition = null);
     }
 }