attempt at unifying directive presentation

Author: rsill-neo4j

modules/ROOT/pages/directives/custom-logic.adoc

@@ -7,7 +7,9 @@
 The `@cypher` directive binds a GraphQL field to the results of a Cypher query.
 This directive can be used both for properties in a type or as top level queries.
 
-=== Global variables
+=== Definition
+
+==== Global variables
 
 Global variables are available for use within the Cypher statement, and can be applied to the `@cypher` directive.
 
@@ -90,14 +92,14 @@ type Query {
 |===
 
 
-=== Return values
+==== Return values
 
 The return value of Cypher statements must always be of the same type to which the directive is applied.
 
 The variable must also be aliased with a name that is the same as the one passed to `columnName`.
 This can be the name of a node, relationship query, or an alias in the `RETURN` statement of the Cypher statement.
 
-==== Scalar values
+===== Scalar values
 
 Cypher statements must return a value which matches the scalar type to which the directive was applied.
 For example:
@@ -109,7 +111,7 @@ type Query {
 }
 ----
 
-==== Object types
+===== Object types
 
 When returning an object type, all fields of the type must be available in the Cypher return value. 
 This can be achieved by either returning the entire object from the Cypher query, or returning a map of the fields which are required for the object type. 
@@ -152,7 +154,7 @@ type Query {
 The downside of the latter approach is that you need to adjust the return object as you change your object type definition.
 
 
-=== Input arguments
+==== Input arguments
 
 The `@cypher` statement can access the query parameters by prepending `$` to the parameter name. 
 For example:
@@ -174,7 +176,7 @@ query {
 ----
 
 
-=== Usage examples
+=== Usage
 
 The `@cypher` directive can be used in different contexts, such as the ones described in this section.
 
@@ -383,7 +385,11 @@ directive @customResolver(
 ) on FIELD_DEFINITION
 ----
 
-=== The `requires` argument
+=== Usage
+
+// tba - an example without requires argument (?)
+
+==== The `requires` argument
 
 The `requires` argument can be used:
 

modules/ROOT/pages/directives/database-mapping.adoc

@@ -10,10 +10,16 @@ Each type in your GraphQL type definitions can be mapped to an entity in your Ne
 
 == `@relationship`
 
+=== Definition
+
+// tba
+
+=== Usage
+
 Relationships are represented by marking particular fields with a directive -- in this case, `@relationship`. 
 It defines the relationship type in the database, as well as which direction that relationship goes in.
 
-To add a second node type, "Actor", and connect the two together, you should do the following:
+To add two node types, "Movie" and "Actor", and connect the two:
 
 [source, graphql, indent=0]
 ----
@@ -28,8 +34,14 @@ type Actor {
 }
 ----
 
-Note that, in this case, there is a directive on each "end" of the relationship, but it is not essential.
+[NOTE]
+====
+The `@relationship` directive is used twice, once on each end of the relationship.
+This is the standard way of modeling a relationship with the GraphQL library.
+However, it is not a requirement of the type definitions themselves and relationships can deliberately be underspecified, for example to limit access through the API layer.
+====
 
+ Also see xref::/directives/schema-configuration/field-configuration/#_relationship[`@relationship` field configuration].
 
 == `@relationshipProperties`
 
@@ -70,9 +82,14 @@ Note that in addition to this type, there is an added key `properties` in the ex
 For more information, see xref::/types/relationships.adoc[Type definitions -> Relationships].
 
 
-[[type-definitions-node]]
 == `@node`
 
+=== Definition
+
+// tba
+
+=== Usage
+
 The most basic mapping uses GraphQL type names to map to a Neo4j node label.
 For example, to represent a node with the label "Movie" and a single property "title" of type string:
 
@@ -84,13 +101,15 @@ type Movie {
 ----
 
 With the `@node` directive, you have more control over this mapping, and you can specify the configuration of a GraphQL object type which represents a Neo4j node.
-It can be appended with the following optional parameters:
 
+==== The `labels` parameter
 
-[discrete]
-=== `labels`
+You can append the optional parameters `labels` to a GraphQL object with the `@node` directive.
+This parameter lists the labels to be used in Neo4j instead of the GraphQL type name.
 
-This parameter defines the list of label to be used in Neo4j instead of the GraphQL type name:
+.Querying a field with the `labels` parameter
+====
+Consider the following type definition:
 
 [source, graphql, indent=0]
 ----
@@ -99,7 +118,7 @@ type Dog @node(labels: ["K9"]) {
 }
 ----
 
-This way, the following query:
+Here is a query against the `Dog` node:
 
 [source, graphql, indent=0]
 ----
@@ -110,15 +129,20 @@ This way, the following query:
 }
 ----
 
-Generates the Cypher query:
+The following Cypher is generated:
 
 [source, cypher, indent=0]
 ----
 MATCH (this: K9)
 RETURN this { .name } as name
 ----
+====
 
-If the GraphQL type name should still be used as a label, it needs to be specified as well:
+If you want to use the GraphQL type name as a label, specifiy both.
+
+.Querying a field with two entries for the `labels` parameter
+====
+Consider the following type definition:
 
 [source, graphql, indent=0]
 ----
@@ -127,7 +151,8 @@ type Dog @node(labels: ["Dog", "K9"]) {
 }
 ----
 
-This way, the following query:
+Here is an example for a query against the `Dog` node 
+
 
 [source, graphql, indent=0]
 ----
@@ -138,13 +163,14 @@ This way, the following query:
 }
 ----
 
-Generates the Cypher query:
+The following Cypher is generated:
 
 [source, cypher, indent=0]
 ----
 MATCH (this:Dog:K9)
 RETURN this { .name } as this
 ----
+====
 
 [NOTE]
 ====
@@ -161,12 +187,18 @@ type Dog @node(labels: ["K9", "Dog"]) {
 }
 ----
 
+See xref::/directives/indexes-and-constraints.adoc#_unique_node_property_constraints[`@unique`] to learn more about the `@unique` directive.
 
-[discrete]
-=== Using `$jwt` and `$context`
+
+==== Using `$jwt` and `$context`
 
 In some cases, you may want to generate dynamic labels depending on the user requesting. 
-For that, you can use the variable `$jwt` to define a custom label in the JWT:
+You can use the variable `$jwt` to define a custom label in the JWT.
+
+
+.Querying a field with a `$jwt` variable in the `labels` parameter
+====
+Consider the following type definition:
 
 [source, graphql, indent=0]
 ----
@@ -186,13 +218,14 @@ The following query yields a different Cypher query depending on the user JWT:
 }
 ----
 
-Assuming there is a user with the value `"username": "arthur"` in JWT, the Cypher query looks like:
+Assuming there is a user with the value `"username": "arthur"` in JWT, the Cypher query looks like this:
 
 [source, cypher, indent=0]
 ----
 MATCH (this:arthur)
 RETURN this { .name } as this
 ----
+====
 
 Similarly, context values can be passed directly:
 
@@ -203,7 +236,7 @@ type User @node(label: ["$context.appId"]) {
 }
 ----
 
-When running the server with Apollo:
+For example, if you are running the server with Apollo:
 
 [source, js, indent=0]
 ----
@@ -217,9 +250,14 @@ await startStandaloneServer(server, {
 ----
 
 
-[[type-definitions-alias]]
 == `@alias`
 
+=== Definition
+
+// tba
+
+=== Usage
+
 This directive maps a GraphQL field to a Neo4j property on a node or relationship.
 It can be used on any fields that are not `@cypher` or `@relationship` fields.
 

modules/ROOT/pages/directives/index.adoc

@@ -5,50 +5,50 @@
 
 The Neo4j GraphQL Library provides the following directives to be used whilst defining types:
 
-== Database mapping
+== Security
 
 [cols="2,5"]
 |===
 | Directive | Description
 
-| xref::/directives/database-mapping.adoc#_relationship[`@relationship`]
-| Configures xref::/types/relationships.adoc[relationships] between object types.
+| xref::/security/authentication.adoc#_authentication[`@authentication`]
+| Requires authentication checks when accessing the type.
 
-| xref::/directives/database-mapping.adoc#_relationshipproperties[`@relationshipProperties`]
-a| Required to differentiate interfaces that are used for relationship properties, and otherwise.
+| xref::/security/authorization.adoc[`@authorization`]
+| Specifies authorization rules for queries and mutations on the type.
 
-| xref::/directives/database-mapping.adoc#type-definitions-node[`@node`]
-| Specifies the configuration of a GraphQL object type which represents a Neo4j node.
+| xref::/security/configuration.adoc#_jwt[`@jwt`]
+| Configures the JWT authentication and authorization filters to include additional JWT claims.
 
-| xref::/directives/database-mapping.adoc#type-definitions-alias[`@alias`]
-| Maps a GraphQL schema field to a Neo4j property on a node or relationship.
+| xref::/security/configuration.adoc#_jwtclaim[`@jwtClaim`]
+| Used in combination with `@jwt`.
+Configures the JWT authentication and authorization filters to include an additional JWT claim which is either nested or using special characters not supported by GraphQL.
 
-| xref::/types/relationships.adoc#_declarerelationship[`@declareRelationship`]
-| Configure relationships to be implemented on object types.
+| xref::/security/subscriptions-authorization.adoc[`@subscriptionsAuthorization`]
+| Specifies authorization rules for subscriptions on the type.
 
 |===
 
-== Security
+== Database mapping
 
 [cols="2,5"]
 |===
 | Directive | Description
 
-| xref::/security/authentication.adoc[`@authentication`]
-| Requires authentication checks when accessing the type.
+| xref::/directives/database-mapping.adoc#_relationship[`@relationship`]
+| Configures xref::/types/relationships.adoc[relationships] between object types. Also see xref::/directives/schema-configuration/field-configuration.adoc#_relationship[`@relationship` field configuration].
 
-| xref::/security/authorization.adoc[`@authorization`]
-| Specifies authorization rules for queries and mutations on the type.
+| xref::/directives/database-mapping.adoc#_relationshipproperties[`@relationshipProperties`]
+a| Required to differentiate interfaces that are used for relationship properties, and otherwise.
 
-| xref::/security/configuration.adoc#_the_jwt_directive[`@jwt`]
-| Configures the JWT authentication and authorization filters to include additional JWT claims.
+| xref::/directives/database-mapping.adoc#_node[`@node`]
+| Specifies the configuration of a GraphQL object type which represents a Neo4j node.
 
-| xref::/security/configuration.adoc#_the_jwtclaim_directive[`@jwtClaim`]
-| Used in combination with `@jwt`.
-Configures the JWT authentication and authorization filters to include an additional JWT claim which is either nested or using special characters not supported by GraphQL.
+| xref::/directives/database-mapping.adoc#_alias[`@alias`]
+| Maps a GraphQL schema field to a Neo4j property on a node or relationship.
 
-| xref::/security/subscriptions-authorization.adoc[`@subscriptionsAuthorization`]
-| Specifies authorization rules for subscriptions on the type.
+| xref::/types/relationships.adoc#_declarerelationship[`@declareRelationship`]
+| Configure relationships to be implemented on object types.
 
 |===
 
@@ -84,7 +84,7 @@ Configures the JWT authentication and authorization filters to include an additi
 | xref::/directives/schema-configuration/type-configuration.adoc#type-definitions-default-values-default[`@default`]
 | Allows the setting of a default value for a field during object creation.
 
-| xref::/directives/schema-configuration/type-configuration.adoc#type-definitions-plural[`@plural`]
+| xref::/directives/schema-configuration/type-configuration.adoc#_plural[`@plural`]
 | Redefines how to compose the plural of the type for the generated operations.
 Particularly useful for types that are not correctly pluralized or are non-English words.
 
@@ -157,7 +157,7 @@ of any required fields that is passed as arguments to the custom resolver.
 |===
 | Directive | Description
 
-| xref:/integrations/relay-compatibility.adoc[`@relayId`]
+| xref:/integrations/relay-compatibility.adoc#_relayid[`@relayId`]
 | Specifies that the field should be used as the global node identifier for Relay.
 
 |===