Clarified when/how to register resource definitions (#1015)

Author: Bart Koelman

docs/usage/caching.md

@@ -60,7 +60,7 @@ ETag: "356075D903B8FE8D9921201A7E7CD3F9"
 }
 ```
 
-Note: To just poll for changes (without fetching them), send a HEAD request instead:
+**Note:** To just poll for changes (without fetching them), send a HEAD request instead:
 
 ```http
 HEAD /articles?sort=-lastModifiedAt HTTP/1.1

docs/usage/extensibility/layer-overview.md

@@ -23,7 +23,7 @@ on your needs, you may want to replace other parts by deriving from the built-in
 
 ## Replacing injected services
 
-**Note:** If you are using auto-discovery, then resource services, repositories and resource definitions will be automatically registered for you.
+**Note:** If you're using [auto-discovery](~/usage/resource-graph.md#auto-discovery), then resource services, repositories and resource definitions will be automatically registered for you.
 
 Replacing built-in services is done on a per-resource basis and can be done through dependency injection in your Startup.cs file.
 For convenience, extension methods are provided to register layers on all their implemented interfaces.

docs/usage/extensibility/repositories.md

@@ -9,13 +9,15 @@ The repository should then be registered in Startup.cs.
 public void ConfigureServices(IServiceCollection services)
 {
     services.AddScoped<IResourceRepository<Article>, ArticleRepository>();
+    services.AddScoped<IResourceReadRepository<Article>, ArticleRepository>();
+    services.AddScoped<IResourceWriteRepository<Article>, ArticleRepository>();
 }
 ```
 
 In v4.0 we introduced an extension method that you can use to register a resource repository on all of its JsonApiDotNetCore interfaces.
-This is helpful when you implement a subset of the resource interfaces and want to register them all in one go.
+This is helpful when you implement (a subset of) the resource interfaces and want to register them all in one go.
 
-Note: If you're using service discovery, this happens automatically.
+**Note:** If you're using [auto-discovery](~/usage/resource-graph.md#auto-discovery), this happens automatically.
 
 ```c#
 public class Startup

docs/usage/extensibility/resource-definitions.md

@@ -3,11 +3,24 @@
 _since v2.3.4_
 
 Resource definitions provide a resource-oriented way to handle custom business logic (irrespective of the originating endpoint).
-
 They are resolved from the dependency injection container, so you can inject dependencies in their constructor.
 
+In v4.2 we introduced an extension method that you can use to register your resource definition.
+
+**Note:** If you're using [auto-discovery](~/usage/resource-graph.md#auto-discovery), this happens automatically.
+
+```c#
+public class Startup
+{
+    public void ConfigureServices(IServiceCollection services)
+    {
+        services.AddResourceDefinition<ArticleDefinition>();
+    }
+}
+```
+
 **Note:** Prior to the introduction of auto-discovery (in v3), you needed to register the
-`ResourceDefinition` on the container yourself:
+resource definition on the container yourself:
 
 ```c#
 services.AddScoped<ResourceDefinition<Product>, ProductResource>();
@@ -29,7 +42,7 @@ from Entity Framework Core `IQueryable` execution.
 There are some cases where you want attributes (or relationships) conditionally excluded from your resource response.
 For example, you may accept some sensitive data that should only be exposed to administrators after creation.
 
-Note: to exclude attributes unconditionally, use `[Attr(Capabilities = ~AttrCapabilities.AllowView)]` on a resource class property.
+**Note:** to exclude attributes unconditionally, use `[Attr(Capabilities = ~AttrCapabilities.AllowView)]` on a resource class property.
 
 ```c#
 public class UserDefinition : JsonApiResourceDefinition<User>

docs/usage/extensibility/services.md

@@ -137,9 +137,9 @@ public class Startup
 ```
 
 In v3.0 we introduced an extension method that you can use to register a resource service on all of its JsonApiDotNetCore interfaces.
-This is helpful when you implement a subset of the resource interfaces and want to register them all in one go.
+This is helpful when you implement (a subset of) the resource interfaces and want to register them all in one go.
 
-Note: If you're using service discovery, this happens automatically.
+**Note:** If you're using [auto-discovery](~/usage/resource-graph.md#auto-discovery), this happens automatically.
 
 ```c#
 public class Startup

docs/usage/resource-graph.md

@@ -1,11 +1,10 @@
 # The Resource Graph
 
-_NOTE: prior to v4 this was called the `ContextGraph`_
-
 The `ResourceGraph` is a map of all the JSON:API resources and their relationships that your API serves.
-
 It is built at app startup and available as a singleton through Dependency Injection.
 
+**Note:** Prior to v4 this was called the `ContextGraph`.
+
 ## Constructing The Graph
 
 There are three ways the resource graph can be created: