Another pass over documentation (#770)

Another pass over documentation

Author: Bart Koelman

docs/getting-started/install.md

@@ -2,14 +2,17 @@
 
 Click [here](https://www.nuget.org/packages/JsonApiDotnetCore/) for the latest NuGet version.
 
+### CLI
 ```
 dotnet add package JsonApiDotnetCore
 ```
 
+### Visual Studio
 ```powershell
 Install-Package JsonApiDotnetCore
 ```
 
+### *.csproj
 ```xml
 <ItemGroup>
   <!-- Be sure to check NuGet for the latest version # -->

docs/index.md

@@ -1,24 +1,25 @@
-# JSON API .Net Core
+# JsonApiDotNetCore
 
-A [{ json:api }](https://jsonapi.org) web application framework for .Net Core.
+A [json:api](https://jsonapi.org) web application framework for .NET Core.
 
 ## Objectives
 
 ### 1. Eliminate Boilerplate
 
-The goal of this package is to facility the development of json:api applications that leverage the full range
-of features provided by the specification.
+The goal of this package is to facilitate the development of APIs that leverage the full range
+of features provided by the json:api specification.
 
-Eliminate CRUD boilerplate and provide the following features across all your resource endpoints:
+Eliminate CRUD boilerplate and provide the following features across your resource endpoints, from HTTP all the way down to the database:
 
-- Relationship inclusion and navigation
 - Filtering
 - Sorting
 - Pagination
 - Sparse field selection
-- Checkout the [example requests](request-examples) to see the kind of features you will get out of the box
+- Relationship inclusion and navigation
+
+Checkout the [example requests](request-examples) to see the kind of features you will get out of the box.
 
 ### 2. Extensibility
 
-This library relies heavily on an open-generic-based dependency injection model which allows for easy per-resource customization.
+This library relies heavily on an open-generic-based dependency injection model, which allows for easy per-resource customization.
 

docs/usage/extensibility/custom-query-formats.md

@@ -1,6 +1,6 @@
 # Custom Query Formats
 
-For information on the default query parameter formats, see the documentation for each query method.
+For information on the default query string parameter formats, see the documentation for each query method.
 
 In order to customize the query formats, you need to implement the `IQueryParameterParser` interface and inject it.
 

docs/usage/extensibility/layer-overview.md

@@ -35,7 +35,7 @@ public void ConfigureServices(IServiceCollection services)
     services.AddResourceService<FooService>();
 
     // custom repository
-    services.AddScoped<AFooRepository>();
+    services.AddScoped<FooRepository>();
 }
 ```
 
@@ -46,11 +46,9 @@ Prior to v3.0.0 you could do it like so:
 public void ConfigureServices(IServiceCollection services)
 {
     // custom service
-    services.AddScoped<IResourceRepository<Foo>, FooService>();
+    services.AddScoped<IResourceService<Foo>, FooService>();
 
     // custom repository
-    services.AddScoped<IResourceRepository<Foo>, FooService>();
-
-    // ...
+    services.AddScoped<IResourceRepository<Foo>, FooRepository>();
 }
 ```

docs/usage/extensibility/services.md

@@ -91,16 +91,16 @@ IResourceService
 |
 +-- IResourceQueryService
 |   |
-¦   +-- IGetAllService
-¦   ¦   GET /
+|   +-- IGetAllService
+|   |   GET /
 |   |
-¦   +-- IGetByIdService
+|   +-- IGetByIdService
 |   |   GET /{id}
 |   |
-¦   +-- IGetRelationshipService
+|   +-- IGetRelationshipService
 |   |   GET /{id}/{relationship}
 |   |
-¦   +-- IGetRelationshipsService
+|   +-- IGetRelationshipsService
 |       GET /{id}/relationships/{relationship}
 |
 +-- IResourceCommandService

docs/usage/filtering.md

@@ -1,6 +1,6 @@
 # Filtering
 
-Resources can be filtered by attributes using the `filter` query parameter.
+Resources can be filtered by attributes using the `filter` query string parameter.
 By default, all attributes are filterable.
 The filtering strategy we have selected, uses the following form.
 
@@ -35,7 +35,7 @@ GET /api/articles?filter[ordinal]=gt:1,lt:100 HTTP/1.1
 GET /api/articles?filter[ordinal]=gt:1&filter[ordinal]=lt:100 HTTP/1.1
 ```
 
-Aside from filtering on the resource being requested (top-level), filtering on single-depth related resources that are being included can be done too.
+Aside from filtering on the resource being requested (top-level), filtering on single-depth related resources can be done too.
 
 ```http
 GET /api/articles?include=author&filter[title]=like:marketing&filter[author.lastName]=Smith HTTP/1.1

docs/usage/options.md

@@ -16,7 +16,7 @@ public class Startup
 }
 ```
 
-## Client Generated Ids
+## Client Generated IDs
 
 By default, the server will respond with a 403 Forbidden HTTP Status Code if a POST request is received with a client-generated ID.
 
@@ -36,6 +36,7 @@ You can also include the total number of records in each request. Note that when
 options.DefaultPageSize = 25;
 options.MaximumPageSize = 100;
 options.MaximumPageNumber = 50;
+options.IncludeTotalRecordCount = true;
 ```
 
 ## Relative Links

docs/usage/resources/resource-definitions.md

@@ -92,7 +92,7 @@ public class AccountDefinition : ResourceDefinition<Account>
 
 _since v3.0.0_
 
-You can define additional query parameters and the query that should be used.
+You can define additional query string parameters and the query that should be used.
 If the key is present in a filter request, the supplied query will be used rather than the default behavior.
 
 ```c#

docs/usage/routing.md

@@ -1,7 +1,7 @@
 # Routing
 
 By default the library will configure routes for each controller.
-Based on the recommendations outlined in the json:api spec, routes are camel-cased.
+Based on the [recommendations](https://jsonapi.org/recommendations/) outlined in the json:api spec, routes are camel-cased.
 
 ```http
 GET /api/compoundModels HTTP/1.1

docs/usage/sparse-field-selection.md

@@ -1,6 +1,6 @@
 # Sparse Field Selection
 
-As an alternative to returning all attributes from a resource, the fields query parameter can be used to select only a subset.
+As an alternative to returning all attributes from a resource, the `fields` query string parameter can be used to select only a subset.
 This can be used on the resource being requested (top-level), as well as on single-depth related resources that are being included.
 
 Top-level example:

docs/usage/toc.md

@@ -4,15 +4,15 @@
 ## [Resource Definitions](resources/resource-definitions.md)
 
 # [Resource Graph](resource-graph.md)
-# [Metadata](meta.md)
-# [Filtering](filtering.md)
 # [Options](options.md)
-# [Errors](errors.md)
-# [Including Relationships](including-relationships.md)
-# [Pagination](pagination.md)
-# [Routing](routing.md)
+# [Filtering](filtering.md)
 # [Sorting](sorting.md)
+# [Pagination](pagination.md)
 # [Sparse Field Selection](sparse-field-selection.md)
+# [Including Relationships](including-relationships.md)
+# [Routing](routing.md)
+# [Errors](errors.md)
+# [Metadata](meta.md)
 
 # Extensibility
 ## [Layer Overview](extensibility/layer-overview.md)