Add descriptions to executable definitions

IvanGoncharov · IvanGoncharov · commit 14cce6147cc1 · 2021-10-07T19:15:34.000+03:00
diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md
@@ -127,8 +127,10 @@ ExecutableDefinition :
   - OperationDefinition
   - FragmentDefinition
 
+Description : StringValue
+
 OperationDefinition :
-  - OperationType Name? VariableDefinitions? Directives? SelectionSet
+  - Description? OperationType Name? VariableDefinitions? Directives? SelectionSet
   - SelectionSet
 
 OperationType : one of `query` `mutation` `subscription`
@@ -152,7 +154,7 @@ FragmentSpread : ... FragmentName Directives?
 
 InlineFragment : ... TypeCondition? Directives? SelectionSet
 
-FragmentDefinition : fragment FragmentName TypeCondition Directives? SelectionSet
+FragmentDefinition : Description? fragment FragmentName TypeCondition Directives? SelectionSet
 
 FragmentName : Name but not `on`
 
@@ -187,7 +189,7 @@ ObjectField[Const] : Name : Value[?Const]
 
 VariableDefinitions : ( VariableDefinition+ )
 
-VariableDefinition : Variable : Type DefaultValue? Directives[Const]?
+VariableDefinition : Description? Variable : Type DefaultValue? Directives[Const]?
 
 Variable : $ Name
 
@@ -235,8 +237,6 @@ SchemaExtension :
 
 RootOperationTypeDefinition : OperationType : NamedType
 
-Description : StringValue
-
 TypeDefinition :
   - ScalarTypeDefinition
   - ObjectTypeDefinition
diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md
@@ -274,6 +274,18 @@ operations, each operation must be named. When submitting a Document with
 multiple operations to a GraphQL service, the name of the desired operation to
 be executed must also be provided.
 
+## Descriptions
+
+Description : StringValue
+
+Documentation is a first-class feature of GraphQL.
+GraphQL descriptions are defined using the Markdown syntax (as specified by
+[CommonMark](https://commonmark.org/)). Description strings (often {BlockString})
+occur immediately before the definition they describe.
+
+GraphQL definitions (e.g. queries, fragments, types, fields, arguments, etc.)
+which can be described should provide a {Description} unless they are considered
+self descriptive.
 
 ## Operations
 
