Add descriptions to executable definitions

Author: IvanGoncharov

spec/Appendix B -- Grammar Summary.md

@@ -147,9 +147,11 @@ ExecutableDefinition :
 - OperationDefinition
 - FragmentDefinition
 
+Description : StringValue
+
 OperationDefinition :
 
-- OperationType Name? VariablesDefinition? Directives? SelectionSet
+- Description? OperationType Name? VariablesDefinition? Directives? SelectionSet
 - SelectionSet
 
 OperationType : one of `query` `mutation` `subscription`
@@ -174,7 +176,7 @@ FragmentSpread : ... FragmentName Directives?
 
 InlineFragment : ... TypeCondition? Directives? SelectionSet
 
-FragmentDefinition : fragment FragmentName TypeCondition Directives?
+FragmentDefinition : Description? fragment FragmentName TypeCondition Directives?
 SelectionSet
 
 FragmentName : Name but not `on`
@@ -213,7 +215,7 @@ ObjectField[Const] : Name : Value[?Const]
 
 VariablesDefinition : ( VariableDefinition+ )
 
-VariableDefinition : Variable : Type DefaultValue? Directives[Const]?
+VariableDefinition : Description? Variable : Type DefaultValue? Directives[Const]?
 
 Variable : $ Name
 
@@ -268,8 +270,6 @@ SchemaExtension :
 
 RootOperationTypeDefinition : OperationType : NamedType
 
-Description : StringValue
-
 TypeDefinition :
 
 - ScalarTypeDefinition

spec/Section 2 -- Language.md

@@ -275,6 +275,19 @@ 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
 
 OperationDefinition :