Initial documentation descriptions for generated API

src/augment/ast.js

@@ -192,11 +192,19 @@ export const buildDirectiveDefinition = ({
   };
 };
 
-export const buildDescription = ({ value, block = false }) => ({
-  kind: Kind.STRING,
-  value,
-  block
-});
+export const buildDescription = ({ value, block = false, config = {} }) => {
+  // If boolean and not false, then default is to generate documentation
+  if (
+    typeof config.documentation !== 'boolean' ||
+    config.documentation !== false
+  ) {
+    return {
+      kind: Kind.STRING,
+      value,
+      block
+    };
+  }
+};
 
 export const buildSelectionSet = ({ selections = [] }) => {
   return {

src/augment/fields.js

@@ -6,7 +6,7 @@ import {
   OperationType
 } from './types/types';
 import { OrderingArgument, buildPropertyOrderingValues } from './input-values';
-import { buildField, buildName, buildNamedType } from './ast';
+import { buildField, buildName, buildNamedType, buildDescription } from './ast';
 
 /**
  * The name of the Neo4j system ID field
@@ -194,7 +194,8 @@ export const buildNeo4jSystemIDField = ({
   typeName,
   propertyOutputFields,
   nodeInputTypeMap,
-  config
+  config,
+  isRelationship = false
 }) => {
   const queryTypeNameLower = OperationType.QUERY.toLowerCase();
   if (shouldAugmentType(config, queryTypeNameLower, typeName)) {
@@ -207,10 +208,16 @@ export const buildNeo4jSystemIDField = ({
     const systemIDIndex = propertyOutputFields.findIndex(
       e => e.name.value === Neo4jSystemIDField
     );
+    let entityDescription = 'node';
+    if (isRelationship) entityDescription = 'relationship';
     const systemIDField = buildField({
       name: buildName({ name: neo4jInternalIDConfig.name }),
       type: buildNamedType({
         name: GraphQLString.name
+      }),
+      description: buildDescription({
+        value: `Generated field for querying the Neo4j [system id](https://neo4j.com/docs/cypher-manual/current/functions/scalar/#functions-id) of this ${entityDescription}.`,
+        config
       })
     });
     if (systemIDIndex >= 0) {

src/augment/types/node/mutation.js

@@ -3,7 +3,8 @@ import {
   buildField,
   buildName,
   buildNamedType,
-  buildInputValue
+  buildInputValue,
+  buildDescription
 } from '../../ast';
 import {
   DirectiveDefinition,
@@ -32,6 +33,9 @@ const NodeMutation = {
   MERGE: 'Merge'
 };
 
+const GRANDSTACK_DOCS = `https://grandstack.io/docs`;
+const GRANDSTACK_DOCS_SCHEMA_AUGMENTATION = `${GRANDSTACK_DOCS}/graphql-schema-generation-augmentation`;
+
 /**
  * Given the results of augmentNodeTypeFields, builds or augments
  * the AST definitions of the Mutation operation fields and any
@@ -84,7 +88,7 @@ export const augmentNodeMutationAPI = ({
  */
 const buildNodeMutationField = ({
   mutationType,
-  mutationAction,
+  mutationAction = '',
   primaryKey,
   typeName,
   propertyInputValues,
@@ -106,7 +110,7 @@ const buildNodeMutationField = ({
       name: typeName
     })
   ) {
-    const mutationField = {
+    const mutationConfig = {
       name: buildName({ name: mutationName }),
       args: buildNodeMutationArguments({
         operationName: mutationAction,
@@ -122,21 +126,38 @@ const buildNodeMutationField = ({
         config
       })
     };
+    let mutationField = undefined;
+    let mutationDescriptionUrl = '';
     if (mutationAction === NodeMutation.CREATE) {
-      mutationFields.push(buildField(mutationField));
+      mutationField = mutationConfig;
+      mutationDescriptionUrl =
+        '[creating](https://neo4j.com/docs/cypher-manual/4.1/clauses/create/#create-nodes)';
     } else if (mutationAction === NodeMutation.UPDATE) {
-      if (primaryKey && mutationField.args.length > 1) {
-        mutationFields.push(buildField(mutationField));
+      if (primaryKey && mutationConfig.args.length > 1) {
+        mutationField = mutationConfig;
+        mutationDescriptionUrl =
+          '[updating](https://neo4j.com/docs/cypher-manual/4.1/clauses/set/#set-update-a-property)';
       }
     } else if (mutationAction === NodeMutation.MERGE) {
       if (primaryKey) {
-        mutationFields.push(buildField(mutationField));
+        mutationField = mutationConfig;
+        mutationDescriptionUrl =
+          '[merging](https://neo4j.com/docs/cypher-manual/4.1/clauses/merge/#query-merge-node-derived)';
       }
     } else if (mutationAction === NodeMutation.DELETE) {
       if (primaryKey) {
-        mutationFields.push(buildField(mutationField));
+        mutationField = mutationConfig;
+        mutationDescriptionUrl =
+          '[deleting](https://neo4j.com/docs/cypher-manual/4.1/clauses/delete/#delete-delete-single-node)';
       }
     }
+    if (mutationField) {
+      mutationField.description = buildDescription({
+        value: `[Generated mutation](${GRANDSTACK_DOCS_SCHEMA_AUGMENTATION}/#${mutationAction.toLowerCase()}) for ${mutationDescriptionUrl} a ${typeName} node.`,
+        config
+      });
+      mutationFields.push(buildField(mutationField));
+    }
     operationTypeMap[OperationType.MUTATION].fields = mutationFields;
   }
   return operationTypeMap;

src/augment/types/node/query.js

@@ -4,7 +4,8 @@ import {
   buildField,
   buildInputValue,
   buildName,
-  buildNamedType
+  buildNamedType,
+  buildDescription
 } from '../../ast';
 import {
   DirectiveDefinition,
@@ -18,8 +19,7 @@ import {
   getFieldDefinition,
   getTypeExtensionFieldDefinition,
   isNeo4jIDField,
-  Neo4jSystemIDField,
-  isListTypeField
+  Neo4jSystemIDField
 } from '../../fields';
 import {
   FilteringArgument,
@@ -40,6 +40,9 @@ const NodeQueryArgument = {
   ...FilteringArgument
 };
 
+const GRANDSTACK_DOCS = `https://grandstack.io/docs`;
+const GRANDSTACK_DOCS_GENERATED_QUERIES = `${GRANDSTACK_DOCS}/graphql-schema-generation-augmentation#generated-queries`;
+
 /**
  * Given the results of augmentNodeTypeFields, builds or augments
  * the AST definition of the Query operation field and any
@@ -190,6 +193,10 @@ const buildNodeQueryField = ({
         directives: buildNodeQueryDirectives({
           typeName,
           config
+        }),
+        description: buildDescription({
+          value: `[Generated query](${GRANDSTACK_DOCS_GENERATED_QUERIES}) for ${typeName} type nodes.`,
+          config
         })
       })
     );

src/augment/types/relationship/mutation.js

@@ -1,5 +1,4 @@
 import { RelationshipDirectionField } from './relationship';
-import { buildNodeOutputFields } from './query';
 import { shouldAugmentRelationshipField } from '../../augment';
 import { OperationType } from '../../types/types';
 import {
@@ -23,7 +22,8 @@ import {
   buildNamedType,
   buildField,
   buildObjectType,
-  buildInputObjectType
+  buildInputObjectType,
+  buildDescription
 } from '../../ast';
 import { getPrimaryKey } from '../node/selection';
 import { isExternalTypeExtension } from '../../../federation';
@@ -40,6 +40,10 @@ const RelationshipMutation = {
   MERGE: 'Merge'
 };
 
+const GRANDSTACK_DOCS = `https://grandstack.io/docs`;
+const GRANDSTACK_DOCS_RELATIONSHIP_TYPE_QUERY = `${GRANDSTACK_DOCS}/graphql-relationship-types`;
+const GRANDSTACK_DOCS_SCHEMA_AUGMENTATION = `${GRANDSTACK_DOCS}/graphql-schema-generation-augmentation`;
+
 /**
  * Given the results of augmentRelationshipTypeFields, builds or
  * augments the AST definitions of the Mutation operation fields
@@ -242,7 +246,8 @@ const buildRelationshipMutationAPI = ({
       relationshipName,
       fromType,
       toType,
-      generatedTypeMap
+      generatedTypeMap,
+      config
     });
   }
   return [operationTypeMap, generatedTypeMap];
@@ -272,6 +277,28 @@ const buildRelationshipMutationField = ({
       propertyInputValues.length) ||
     mutationAction === RelationshipMutation.MERGE
   ) {
+    let cypherDocUrl = '';
+    let grandstackDocUrl = '';
+    if (mutationAction === RelationshipMutation.CREATE) {
+      cypherDocUrl =
+        '[creating](https://neo4j.com/docs/cypher-manual/4.1/clauses/create/#create-relationships)';
+      grandstackDocUrl = '#add--remove-relationship';
+    }
+    if (mutationAction === RelationshipMutation.DELETE) {
+      cypherDocUrl =
+        '[deleting](https://neo4j.com/docs/cypher-manual/4.1/clauses/delete/#delete-delete-relationships-only)';
+      grandstackDocUrl = '#add--remove-relationship';
+    }
+    if (mutationAction === RelationshipMutation.UPDATE) {
+      cypherDocUrl =
+        '[updating](https://neo4j.com/docs/cypher-manual/4.1/clauses/set/#set-update-a-property)';
+      grandstackDocUrl = '#update-relationship';
+    }
+    if (mutationAction === RelationshipMutation.MERGE) {
+      cypherDocUrl =
+        '[merging](https://neo4j.com/docs/cypher-manual/4.1/clauses/merge/#query-merge-relationships)';
+      grandstackDocUrl = '#merge-relationship';
+    }
     operationTypeMap[OperationType.MUTATION].fields.push(
       buildField({
         name: buildName({
@@ -293,6 +320,10 @@ const buildRelationshipMutationField = ({
           fromType,
           toType,
           config
+        }),
+        description: buildDescription({
+          value: `[Generated mutation](${GRANDSTACK_DOCS_SCHEMA_AUGMENTATION}/#${grandstackDocUrl.toLowerCase()}) for ${cypherDocUrl} the ${relationshipName} relationship.`,
+          config
         })
       })
     );
@@ -444,7 +475,8 @@ const buildRelationshipMutationOutputType = ({
   relationshipName,
   fromType,
   toType,
-  generatedTypeMap
+  generatedTypeMap,
+  config
 }) => {
   if (
     mutationAction === RelationshipMutation.CREATE ||
@@ -458,7 +490,32 @@ const buildRelationshipMutationOutputType = ({
       fromType,
       toType
     });
-    let fields = buildNodeOutputFields({ fromType, toType });
+    let fields = [
+      buildField({
+        name: buildName({
+          name: RelationshipDirectionField.FROM
+        }),
+        type: buildNamedType({
+          name: fromType
+        }),
+        description: buildDescription({
+          value: `Field for the ${fromType} node this ${relationshipName} [relationship](${GRANDSTACK_DOCS_RELATIONSHIP_TYPE_QUERY}) is coming from.`,
+          config
+        })
+      }),
+      buildField({
+        name: buildName({
+          name: RelationshipDirectionField.TO
+        }),
+        type: buildNamedType({
+          name: toType
+        }),
+        description: buildDescription({
+          value: `Field for the ${toType} node this ${relationshipName} [relationship](${GRANDSTACK_DOCS_RELATIONSHIP_TYPE_QUERY}) is going to.`,
+          config
+        })
+      })
+    ];
     if (
       mutationAction === RelationshipMutation.CREATE ||
       mutationAction === RelationshipMutation.UPDATE ||