Skip to content
This repository was archived by the owner on Sep 3, 2021. It is now read-only.

Commit 310abe5

Browse files
michaeldgrahammichaeldgraham
authored
Initial documentation descriptions for generated API (#515)
* initial documentation comments for generated api * attempted fix for integration test * reversal of failed fix
1 parent 17b34c6 commit 310abe5

12 files changed

+5612
-4952
lines changed

‎src/augment/ast.js

+13-5
Original file line numberDiff line numberDiff line change
@@ -192,11 +192,19 @@ export const buildDirectiveDefinition = ({
192192
};
193193
};
194194

195-
export const buildDescription = ({ value, block = false }) => ({
196-
kind: Kind.STRING,
197-
value,
198-
block
199-
});
195+
export const buildDescription = ({ value, block = false, config = {} }) => {
196+
// If boolean and not false, then default is to generate documentation
197+
if (
198+
typeof config.documentation !== 'boolean' ||
199+
config.documentation !== false
200+
) {
201+
return {
202+
kind: Kind.STRING,
203+
value,
204+
block
205+
};
206+
}
207+
};
200208

201209
export const buildSelectionSet = ({ selections = [] }) => {
202210
return {

‎src/augment/fields.js

+9-2
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ import {
66
OperationType
77
} from './types/types';
88
import { OrderingArgument, buildPropertyOrderingValues } from './input-values';
9-
import { buildField, buildName, buildNamedType } from './ast';
9+
import { buildField, buildName, buildNamedType, buildDescription } from './ast';
1010

1111
/**
1212
* The name of the Neo4j system ID field
@@ -194,7 +194,8 @@ export const buildNeo4jSystemIDField = ({
194194
typeName,
195195
propertyOutputFields,
196196
nodeInputTypeMap,
197-
config
197+
config,
198+
isRelationship = false
198199
}) => {
199200
const queryTypeNameLower = OperationType.QUERY.toLowerCase();
200201
if (shouldAugmentType(config, queryTypeNameLower, typeName)) {
@@ -207,10 +208,16 @@ export const buildNeo4jSystemIDField = ({
207208
const systemIDIndex = propertyOutputFields.findIndex(
208209
e => e.name.value === Neo4jSystemIDField
209210
);
211+
let entityDescription = 'node';
212+
if (isRelationship) entityDescription = 'relationship';
210213
const systemIDField = buildField({
211214
name: buildName({ name: neo4jInternalIDConfig.name }),
212215
type: buildNamedType({
213216
name: GraphQLString.name
217+
}),
218+
description: buildDescription({
219+
value: `Generated field for querying the Neo4j [system id](https://neo4j.com/docs/cypher-manual/current/functions/scalar/#functions-id) of this ${entityDescription}.`,
220+
config
214221
})
215222
});
216223
if (systemIDIndex >= 0) {

‎src/augment/types/node/mutation.js

+29-8
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@ import {
33
buildField,
44
buildName,
55
buildNamedType,
6-
buildInputValue
6+
buildInputValue,
7+
buildDescription
78
} from '../../ast';
89
import {
910
DirectiveDefinition,
@@ -32,6 +33,9 @@ const NodeMutation = {
3233
MERGE: 'Merge'
3334
};
3435

36+
const GRANDSTACK_DOCS = `https://grandstack.io/docs`;
37+
const GRANDSTACK_DOCS_SCHEMA_AUGMENTATION = `${GRANDSTACK_DOCS}/graphql-schema-generation-augmentation`;
38+
3539
/**
3640
* Given the results of augmentNodeTypeFields, builds or augments
3741
* the AST definitions of the Mutation operation fields and any
@@ -84,7 +88,7 @@ export const augmentNodeMutationAPI = ({
8488
*/
8589
const buildNodeMutationField = ({
8690
mutationType,
87-
mutationAction,
91+
mutationAction = '',
8892
primaryKey,
8993
typeName,
9094
propertyInputValues,
@@ -106,7 +110,7 @@ const buildNodeMutationField = ({
106110
name: typeName
107111
})
108112
) {
109-
const mutationField = {
113+
const mutationConfig = {
110114
name: buildName({ name: mutationName }),
111115
args: buildNodeMutationArguments({
112116
operationName: mutationAction,
@@ -122,21 +126,38 @@ const buildNodeMutationField = ({
122126
config
123127
})
124128
};
129+
let mutationField = undefined;
130+
let mutationDescriptionUrl = '';
125131
if (mutationAction === NodeMutation.CREATE) {
126-
mutationFields.push(buildField(mutationField));
132+
mutationField = mutationConfig;
133+
mutationDescriptionUrl =
134+
'[creating](https://neo4j.com/docs/cypher-manual/4.1/clauses/create/#create-nodes)';
127135
} else if (mutationAction === NodeMutation.UPDATE) {
128-
if (primaryKey && mutationField.args.length > 1) {
129-
mutationFields.push(buildField(mutationField));
136+
if (primaryKey && mutationConfig.args.length > 1) {
137+
mutationField = mutationConfig;
138+
mutationDescriptionUrl =
139+
'[updating](https://neo4j.com/docs/cypher-manual/4.1/clauses/set/#set-update-a-property)';
130140
}
131141
} else if (mutationAction === NodeMutation.MERGE) {
132142
if (primaryKey) {
133-
mutationFields.push(buildField(mutationField));
143+
mutationField = mutationConfig;
144+
mutationDescriptionUrl =
145+
'[merging](https://neo4j.com/docs/cypher-manual/4.1/clauses/merge/#query-merge-node-derived)';
134146
}
135147
} else if (mutationAction === NodeMutation.DELETE) {
136148
if (primaryKey) {
137-
mutationFields.push(buildField(mutationField));
149+
mutationField = mutationConfig;
150+
mutationDescriptionUrl =
151+
'[deleting](https://neo4j.com/docs/cypher-manual/4.1/clauses/delete/#delete-delete-single-node)';
138152
}
139153
}
154+
if (mutationField) {
155+
mutationField.description = buildDescription({
156+
value: `[Generated mutation](${GRANDSTACK_DOCS_SCHEMA_AUGMENTATION}/#${mutationAction.toLowerCase()}) for ${mutationDescriptionUrl} a ${typeName} node.`,
157+
config
158+
});
159+
mutationFields.push(buildField(mutationField));
160+
}
140161
operationTypeMap[OperationType.MUTATION].fields = mutationFields;
141162
}
142163
return operationTypeMap;

‎src/augment/types/node/query.js

+10-3
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ import {
44
buildField,
55
buildInputValue,
66
buildName,
7-
buildNamedType
7+
buildNamedType,
8+
buildDescription
89
} from '../../ast';
910
import {
1011
DirectiveDefinition,
@@ -18,8 +19,7 @@ import {
1819
getFieldDefinition,
1920
getTypeExtensionFieldDefinition,
2021
isNeo4jIDField,
21-
Neo4jSystemIDField,
22-
isListTypeField
22+
Neo4jSystemIDField
2323
} from '../../fields';
2424
import {
2525
FilteringArgument,
@@ -40,6 +40,9 @@ const NodeQueryArgument = {
4040
...FilteringArgument
4141
};
4242

43+
const GRANDSTACK_DOCS = `https://grandstack.io/docs`;
44+
const GRANDSTACK_DOCS_GENERATED_QUERIES = `${GRANDSTACK_DOCS}/graphql-schema-generation-augmentation#generated-queries`;
45+
4346
/**
4447
* Given the results of augmentNodeTypeFields, builds or augments
4548
* the AST definition of the Query operation field and any
@@ -190,6 +193,10 @@ const buildNodeQueryField = ({
190193
directives: buildNodeQueryDirectives({
191194
typeName,
192195
config
196+
}),
197+
description: buildDescription({
198+
value: `[Generated query](${GRANDSTACK_DOCS_GENERATED_QUERIES}) for ${typeName} type nodes.`,
199+
config
193200
})
194201
})
195202
);

‎src/augment/types/relationship/mutation.js

+62-5
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
import { RelationshipDirectionField } from './relationship';
2-
import { buildNodeOutputFields } from './query';
32
import { shouldAugmentRelationshipField } from '../../augment';
43
import { OperationType } from '../../types/types';
54
import {
@@ -23,7 +22,8 @@ import {
2322
buildNamedType,
2423
buildField,
2524
buildObjectType,
26-
buildInputObjectType
25+
buildInputObjectType,
26+
buildDescription
2727
} from '../../ast';
2828
import { getPrimaryKey } from '../node/selection';
2929
import { isExternalTypeExtension } from '../../../federation';
@@ -40,6 +40,10 @@ const RelationshipMutation = {
4040
MERGE: 'Merge'
4141
};
4242

43+
const GRANDSTACK_DOCS = `https://grandstack.io/docs`;
44+
const GRANDSTACK_DOCS_RELATIONSHIP_TYPE_QUERY = `${GRANDSTACK_DOCS}/graphql-relationship-types`;
45+
const GRANDSTACK_DOCS_SCHEMA_AUGMENTATION = `${GRANDSTACK_DOCS}/graphql-schema-generation-augmentation`;
46+
4347
/**
4448
* Given the results of augmentRelationshipTypeFields, builds or
4549
* augments the AST definitions of the Mutation operation fields
@@ -242,7 +246,8 @@ const buildRelationshipMutationAPI = ({
242246
relationshipName,
243247
fromType,
244248
toType,
245-
generatedTypeMap
249+
generatedTypeMap,
250+
config
246251
});
247252
}
248253
return [operationTypeMap, generatedTypeMap];
@@ -272,6 +277,28 @@ const buildRelationshipMutationField = ({
272277
propertyInputValues.length) ||
273278
mutationAction === RelationshipMutation.MERGE
274279
) {
280+
let cypherDocUrl = '';
281+
let grandstackDocUrl = '';
282+
if (mutationAction === RelationshipMutation.CREATE) {
283+
cypherDocUrl =
284+
'[creating](https://neo4j.com/docs/cypher-manual/4.1/clauses/create/#create-relationships)';
285+
grandstackDocUrl = '#add--remove-relationship';
286+
}
287+
if (mutationAction === RelationshipMutation.DELETE) {
288+
cypherDocUrl =
289+
'[deleting](https://neo4j.com/docs/cypher-manual/4.1/clauses/delete/#delete-delete-relationships-only)';
290+
grandstackDocUrl = '#add--remove-relationship';
291+
}
292+
if (mutationAction === RelationshipMutation.UPDATE) {
293+
cypherDocUrl =
294+
'[updating](https://neo4j.com/docs/cypher-manual/4.1/clauses/set/#set-update-a-property)';
295+
grandstackDocUrl = '#update-relationship';
296+
}
297+
if (mutationAction === RelationshipMutation.MERGE) {
298+
cypherDocUrl =
299+
'[merging](https://neo4j.com/docs/cypher-manual/4.1/clauses/merge/#query-merge-relationships)';
300+
grandstackDocUrl = '#merge-relationship';
301+
}
275302
operationTypeMap[OperationType.MUTATION].fields.push(
276303
buildField({
277304
name: buildName({
@@ -293,6 +320,10 @@ const buildRelationshipMutationField = ({
293320
fromType,
294321
toType,
295322
config
323+
}),
324+
description: buildDescription({
325+
value: `[Generated mutation](${GRANDSTACK_DOCS_SCHEMA_AUGMENTATION}/#${grandstackDocUrl.toLowerCase()}) for ${cypherDocUrl} the ${relationshipName} relationship.`,
326+
config
296327
})
297328
})
298329
);
@@ -444,7 +475,8 @@ const buildRelationshipMutationOutputType = ({
444475
relationshipName,
445476
fromType,
446477
toType,
447-
generatedTypeMap
478+
generatedTypeMap,
479+
config
448480
}) => {
449481
if (
450482
mutationAction === RelationshipMutation.CREATE ||
@@ -458,7 +490,32 @@ const buildRelationshipMutationOutputType = ({
458490
fromType,
459491
toType
460492
});
461-
let fields = buildNodeOutputFields({ fromType, toType });
493+
let fields = [
494+
buildField({
495+
name: buildName({
496+
name: RelationshipDirectionField.FROM
497+
}),
498+
type: buildNamedType({
499+
name: fromType
500+
}),
501+
description: buildDescription({
502+
value: `Field for the ${fromType} node this ${relationshipName} [relationship](${GRANDSTACK_DOCS_RELATIONSHIP_TYPE_QUERY}) is coming from.`,
503+
config
504+
})
505+
}),
506+
buildField({
507+
name: buildName({
508+
name: RelationshipDirectionField.TO
509+
}),
510+
type: buildNamedType({
511+
name: toType
512+
}),
513+
description: buildDescription({
514+
value: `Field for the ${toType} node this ${relationshipName} [relationship](${GRANDSTACK_DOCS_RELATIONSHIP_TYPE_QUERY}) is going to.`,
515+
config
516+
})
517+
})
518+
];
462519
if (
463520
mutationAction === RelationshipMutation.CREATE ||
464521
mutationAction === RelationshipMutation.UPDATE ||

0 commit comments

Comments
 (0)