Merge pull request #60 from tristanz/operation-name

Clarify operation name

Author: leebyron

README.md

@@ -264,13 +264,14 @@ query HeroNameQuery {
 }
 ```
 
-The initial line, `query HeroNameQuery`, says that we're running a query,
-and tells GraphQL to start with the schema's root query type; in this case,
-`Query`. As defined above, `Query` has a `hero` field that returns a
+The initial line, `query HeroNameQuery`, defines a query with the operation
+name `HeroNameQuery` that starts with the schema's root query type; in this
+case, `Query`. As defined above, `Query` has a `hero` field that returns a
 `Character`, so we'll query for that. `Character` then has a `name` field that
 returns a `String`, so we query for that, completing our query. The result of
 this query would then be:
 
+
 ```json
 {
   "hero": {
@@ -279,6 +280,18 @@ this query would then be:
 }
 ```
 
+Specifying the `query` keyword and an operation name is only required when a
+GraphQL document defines multiple operations.  We therefore could have written
+the previous query with the query shorthand:
+
+```
+{
+  hero {
+    name
+  }
+}
+```
+
 Assuming that the backing data for the GraphQL server identified R2-D2 as the
 hero. The response continues to vary based on the request; if we asked for
 R2-D2's ID and friends with this query:

Section 2 -- Language.md

@@ -43,7 +43,7 @@ name of the desired operation must also be provided.
 
 If a document contains only one query operation, that operation may be
 represented in the shorthand form, which omits the query keyword and
-query name.
+operation name.
 
 ## Operations
 
@@ -52,12 +52,12 @@ There are two types of operations that GraphQL models:
   * query - a read-only fetch.
   * mutation - a write followed by a fetch.
 
-Each operation is represented by a custom name and a selection of fields.
+Each operation is represented by an operation name and a selection of fields.
 
 **Query shorthand**
 
-If a query has no variables or directives or name, the `query` keyword can be
-omitted. This means it must be the only query in the document.
+If a query has no variables or directives or name, the `query` keyword and name
+can be omitted. This means it must be the only query in the document.
 
 Note: many examples below will use the query shorthand syntax.
 

Section 6 -- Execution.md

@@ -6,7 +6,7 @@ This section describes how GraphQL generates a response from a request.
 
 To evaluate a request, the executor must have a parsed `Document` (as defined
 in the “Query Language” part of this spec) and a selected operation name to
-run.
+run if the document defines multiple operations.
 
 The executor should find the `Operation` in the `Document` with the given
 operation name. If no such operation exists, the executor should throw an