Docs: some language cleanup in readme and API reference (#2680)

* Docs: some language cleanup in readme and API reference

* Updates to docs language

* Fixing grammar in API reference doc

README.md

@@ -13,7 +13,7 @@ Looking for help? Find resources [from the community](https://graphql.org/commun
 
 ## Getting Started
 
-An overview of GraphQL in general is available in the
+A general overview of GraphQL is available in the
 [README](https://github.com/graphql/graphql-spec/blob/master/README.md) for the
 [Specification for GraphQL](https://github.com/graphql/graphql-spec). That overview
 describes a simple set of GraphQL examples that exist as [tests](src/__tests__)
@@ -30,16 +30,16 @@ With npm:
 npm install --save graphql
 ```
 
-or alternatively using yarn:
+or using yarn:
 
 ```sh
 yarn add graphql
 ```
 
-GraphQL.js provides two important capabilities: building a type schema, and
+GraphQL.js provides two important capabilities: building a type schema and
 serving queries against that type schema.
 
-First, build a GraphQL type schema which maps to your code base.
+First, build a GraphQL type schema which maps to your codebase.
 
 ```js
 import {
@@ -64,10 +64,9 @@ var schema = new GraphQLSchema({
 });
 ```
 
-This defines a simple schema with one type and one field, that resolves
+This defines a simple schema, with one type and one field, that resolves
 to a fixed value. The `resolve` function can return a value, a promise,
-or an array of promises. A more complex example is included in the top
-level [tests](src/__tests__) directory.
+or an array of promises. A more complex example is included in the top-level [tests](src/__tests__) directory.
 
 Then, serve the result of a query against that type schema.
 
@@ -102,7 +101,7 @@ graphql(schema, query).then((result) => {
 });
 ```
 
-**Note**: Please don't forget to set `NODE_ENV=production` if you are running a production server it will disable some checks that can be useful during development but will significantly improve performance.
+**Note**: Please don't forget to set `NODE_ENV=production` if you are running a production server. It will disable some checks that can be useful during development but will significantly improve performance.
 
 ### Want to ride the bleeding edge?
 
@@ -118,7 +117,7 @@ npm install graphql@git://github.com/graphql/graphql-js.git#npm
 
 ### Using in a Browser
 
-GraphQL.js is a general purpose library and can be used both in a Node server
+GraphQL.js is a general-purpose library and can be used both in a Node server
 and in the browser. As an example, the [GraphiQL](https://github.com/graphql/graphiql/)
 tool is built with GraphQL.js!
 
@@ -130,7 +129,7 @@ custom build configurations look for `.mjs` files!
 
 ### Contributing
 
-We actively welcome pull requests, learn how to [contribute](./.github/CONTRIBUTING.md).
+We actively welcome pull requests. Learn how to [contribute](./.github/CONTRIBUTING.md).
 
 ### Changelog
 

docs/APIReference-Language.md

@@ -106,9 +106,9 @@ export class Source {
 ```
 
 A representation of source input to GraphQL. The name is optional,
-but is mostly useful for clients who store GraphQL documents in
+but it is useful for clients who store GraphQL documents in
 source files; for example, if the GraphQL input is in a file Foo.graphql,
-it might be useful for name to be "Foo.graphql".
+it might be useful for `name` to be "Foo.graphql".
 
 ### getLocation
 
@@ -142,13 +142,13 @@ export type Token = {
 ```
 
 Given a Source object, this returns a Lexer for that source.
-A Lexer is a function that acts like a generator in that every time
+A Lexer is a function that acts as a generator in that every time
 it is called, it returns the next token in the Source. Assuming the
 source lexes, the final Token emitted by the lexer will be of kind
 EOF, after which the lexer will repeatedly return EOF tokens whenever
 called.
 
-The argument to the lexer function is optional, and can be used to
+The argument to the lexer function is optional and can be used to
 rewind or fast forward the lexer to a new position in the source.
 
 ## Parser
@@ -194,7 +194,7 @@ An enum that describes the different kinds of AST nodes.
 function visit(root, visitor, keyMap)
 ```
 
-visit() will walk through an AST using a depth first traversal, calling
+visit() will walk through an AST using a depth-first traversal, calling
 the visitor's enter function at each node in the traversal, and calling the
 leave function after visiting that node and all of its child nodes.
 
@@ -230,10 +230,10 @@ var editedAST = visit(ast, {
 
 Alternatively to providing enter() and leave() functions, a visitor can
 instead provide functions named the same as the kinds of AST nodes, or
-enter/leave visitors at a named key, leading to four permutations of
+enter/leave visitors at a named key, leading to four permutations of the
 visitor API:
 
-1. Named visitors triggered when entering a node a specific kind.
+1. Named visitors triggered when entering a node of a specific kind.
 
 ```js
 visit(ast, {