Merge pull request #289 from neo4j/sortable-docs

Add missing docs about sortable directive

Author: angrykoala

modules/ROOT/pages/directives/index.adoc

@@ -94,6 +94,9 @@ Particularly useful for types that are not correctly pluralized or are non-Engli
 | xref:/directives/schema-configuration/field-configuration.adoc#_settable[`@settable`]
 | Sets the availability of fields on the `create` and `update` inputs.
 
+| xref:/directives/schema-configuration/field-configuration.adoc#_sortable[`@sortable`]
+| Sets the availability of sorting inputs for that field.
+
 | xref:/directives/schema-configuration/field-configuration.adoc#_filterable[`@filterable`]
 | Defines the filters generated for a field.
 

modules/ROOT/pages/directives/schema-configuration/field-configuration.adoc

@@ -398,6 +398,71 @@ input ActorUpdateInput {
 
 This means `actedIn` can be updated on an update, but it is no longer available on `create` operations.
 
+
+== `@sortable`
+
+This directive sets the availability of the input fields for sorting.
+It has a single argument:
+
+* **byValue**: Defaults to true. If disabled, this field is not available for sorting.
+
+=== Definition
+
+[source, graphql, indent=0]
+----
+"""Instructs @neo4j/graphql to generate sorting inputs for this field."""
+directive @sortable(byValue: Boolean! = true) on FIELD_DEFINITION
+----
+
+=== Usage
+
+With this definition:
+
+[source, graphql, indent=0]
+----
+type Movie @node {
+    title: String!
+    description: String! @sortable(byValue: false)
+}
+----
+
+The following input type is generated for Movies:
+
+[source, graphql, indent=0]
+----
+"""
+Fields to sort Movies by. The order in which sorts are applied is not guaranteed when specifying many fields in one MovieSort object.
+"""
+input MovieSort {
+  title: SortDirection
+}
+----
+
+Movies can be sorted by the title, but not by description:
+
+This is valid:
+[source, graphql, indent=0]
+----
+query {
+  movies(sort: {title: DESC}) {
+    title
+  }
+}
+----
+
+This is not valid:
+[source, graphql, indent=0]
+----
+query {
+  movies(sort: {description: DESC}) {
+    title
+  }
+}
+----
+
+
+If no fields are sortable, the type `MovieSort` is not generated, and the `sort` input isn't available.
+
 == `@filterable`
 
 This directive defines the filters generated for the field to which this directive is applied.