Skip to content

Commit 0b91f96

Browse files
committed
Move description section
1 parent 8ac091a commit 0b91f96

File tree

1 file changed

+57
-57
lines changed

1 file changed

+57
-57
lines changed

spec/Section 3 -- Type System.md

Lines changed: 57 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,63 @@ local service to represent data a GraphQL client only accesses locally, or by a
3838
GraphQL service which is itself an extension of another GraphQL service.
3939

4040

41+
## Descriptions
42+
43+
Description : StringValue
44+
45+
Documentation is a first-class feature of GraphQL type systems. To ensure
46+
the documentation of a GraphQL service remains consistent with its capabilities,
47+
descriptions of GraphQL definitions are provided alongside their definitions and
48+
made available via introspection.
49+
50+
To allow GraphQL service designers to easily publish documentation alongside the
51+
capabilities of a GraphQL service, GraphQL descriptions are defined using the
52+
Markdown syntax (as specified by [CommonMark](https://commonmark.org/)). In the
53+
type system definition language, these description strings (often {BlockString})
54+
occur immediately before the definition they describe.
55+
56+
All GraphQL types, fields, arguments and other definitions which can be
57+
described should provide a {Description} unless they are considered self
58+
descriptive.
59+
60+
As an example, this simple GraphQL schema is well described:
61+
62+
```graphql example
63+
"""
64+
A simple GraphQL schema which is well described.
65+
"""
66+
type Query {
67+
"""
68+
Translates a string from a given language into a different language.
69+
"""
70+
translate(
71+
"The original language that `text` is provided in."
72+
fromLanguage: Language
73+
74+
"The translated language to be returned."
75+
toLanguage: Language
76+
77+
"The text to be translated."
78+
text: String
79+
): String
80+
}
81+
82+
"""
83+
The set of languages supported by `translate`.
84+
"""
85+
enum Language {
86+
"English"
87+
EN
88+
89+
"French"
90+
FR
91+
92+
"Chinese"
93+
CH
94+
}
95+
```
96+
97+
4198
## Schema
4299

43100
SchemaDefinition : schema Directives[Const]? { RootOperationTypeDefinition+ }
@@ -169,63 +226,6 @@ Schema extensions have the potential to be invalid if incorrectly defined.
169226
original Schema.
170227

171228

172-
## Descriptions
173-
174-
Description : StringValue
175-
176-
Documentation is a first-class feature of GraphQL type systems. To ensure
177-
the documentation of a GraphQL service remains consistent with its capabilities,
178-
descriptions of GraphQL definitions are provided alongside their definitions and
179-
made available via introspection.
180-
181-
To allow GraphQL service designers to easily publish documentation alongside the
182-
capabilities of a GraphQL service, GraphQL descriptions are defined using the
183-
Markdown syntax (as specified by [CommonMark](https://commonmark.org/)). In the
184-
type system definition language, these description strings (often {BlockString})
185-
occur immediately before the definition they describe.
186-
187-
All GraphQL types, fields, arguments and other definitions which can be
188-
described should provide a {Description} unless they are considered self
189-
descriptive.
190-
191-
As an example, this simple GraphQL schema is well described:
192-
193-
```graphql example
194-
"""
195-
A simple GraphQL schema which is well described.
196-
"""
197-
type Query {
198-
"""
199-
Translates a string from a given language into a different language.
200-
"""
201-
translate(
202-
"The original language that `text` is provided in."
203-
fromLanguage: Language
204-
205-
"The translated language to be returned."
206-
toLanguage: Language
207-
208-
"The text to be translated."
209-
text: String
210-
): String
211-
}
212-
213-
"""
214-
The set of languages supported by `translate`.
215-
"""
216-
enum Language {
217-
"English"
218-
EN
219-
220-
"French"
221-
FR
222-
223-
"Chinese"
224-
CH
225-
}
226-
```
227-
228-
229229
## Types
230230

231231
TypeDefinition :

0 commit comments

Comments
 (0)