Improvements to AS3 docs that are not related to differences from AS2

docs/source/data/data-sources.mdx

@@ -30,7 +30,7 @@ flowchart LR;
 
 ## Open-source implementations
 
-All data source implementations extend the generic [`DataSource` abstract class](https://github.com/apollographql/apollo-server/blob/main/packages/apollo-datasource/src/index.ts), which is included in the `apollo-server` library. Subclasses define whatever logic is required to communicate with a particular store or API.
+All data source implementations extend the generic [`DataSource` abstract class](https://github.com/apollographql/apollo-server/blob/main/packages/apollo-datasource/src/index.ts), which is included in the `apollo-datasource` package. Subclasses of a `DataSource` should define whatever logic is required to communicate with a particular store or API.
 
 Apollo and the larger community maintain the following open-source implementatons:
 

docs/source/data/resolvers.mdx

@@ -164,7 +164,13 @@ Note that you can define your resolvers across as many different files and objec
 
 ## Resolver chains
 
-Whenever a query asks for a field that contains an object type, the query _also_ asks for _at least one field_ of that object (if it didn't, there would be no reason to include the object in the query). A query always "bottoms out" on fields that contain either a scalar or a list of scalars.
+Whenever a query asks for a field that contains an object type, the query _also_ asks for _at least one field_ of that object (if it didn't, there would be no reason to include the object in the query). A query always "bottoms out" on fields that contain either a scalar or an enum, of any list depth and nullability, for example:
+
+```graphql
+type Product {
+  variants: [String!]
+}
+```
 
 Therefore, whenever Apollo Server _resolves_ a field that contains an object type, it always then resolves one or more fields of that object. Those subfields might in turn _also_ contain object types. Depending on your schema, this object-field pattern can continue to an arbitrary depth, creating what's called a **resolver chain**.
 
@@ -388,7 +394,7 @@ const server = new ApolloServer({
 }
 ```
 
-> The fields of the object passed to your `context` function differ if you're using middleware besides Express. [See the API reference for details.](/api/apollo-server/#middleware-specific-context-fields)
+> This example assumes you are using either the `apollo-server` or `apollo-server-express` package, both of which use Express. The fields of the object passed to your `context` function may differ if you're using middleware other than Express. [See the API reference for details.](../api/apollo-server/#middleware-specific-context-fields) For more information on middleware in general, see the [integrations page](../integrations/middleware/).
 
 Context initialization can be asynchronous, allowing database connections and other operations to complete:
 
@@ -411,7 +417,7 @@ A resolver function's return value is treated differently by Apollo Server depen
 |---|---|
 | Scalar / object | <p>A resolver can return a single value or an object, as shown in [Defining a resolver](#defining-a-resolver). This return value is passed down to any nested resolvers via the `parent` argument.</p> |
 | `Array` | <p>Return an array if and only if your schema indicates that the resolver's associated field contains a list.</p><p>After you return an array, Apollo Server executes nested resolvers for each item in the array. </p>|
-| `null` / `undefined` | <p>Indicates that the value for the field could not be found.</p> <p>If your schema indicates that this resolver's field is nullable, then the operation result has a `null` value at the field's position.</p><p>If this resolver's field is _not_ nullable, Apollo Server sets the field's _parent_ to `null`. If necessary, this process continues up the resolver chain until it reaches a field that _is_ nullable. This ensures that a response never includes a `null` value for a non-nullable field.</p>|
+| `null` / `undefined` | <p>Indicates that the value for the field could not be found.</p> <p>If your schema indicates that this resolver's field is nullable, then the operation result has a `null` value at the field's position.</p><p>If this resolver's field is _not_ nullable, Apollo Server sets the field's _parent_ to `null`. If necessary, this process continues up the resolver chain until it reaches a field that _is_ nullable. This ensures that a response never includes a `null` value for a non-nullable field. When this happens, the response's `errors` property will be populated with relevant errors concerning the nullability of that field.</p>|
 | [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises) | <p>Resolvers often perform asynchronous actions, such as fetching from a database or back-end API. To support this, a resolver can return a promise that resolves to any other supported return type.</p> |
 
 

docs/source/monitoring/health-checks.md

@@ -3,14 +3,12 @@ title: Health checks
 description: Determining the health status of the Apollo Server
 ---
 
-Health checks are often used by load balancers to determine if a server is available and ready to start serving traffic.  By default, Apollo Server provides a health check endpoint at `/.well-known/apollo/server-health` which returns a 200 status code if the server has started.
+Health checks are often used by load balancers to determine if a server is available and ready to start serving traffic. By default, Apollo Server provides a health check endpoint at `/.well-known/apollo/server-health` which returns a 200 status code if the server has started.
 
-This basic health check may not be comprehensive enough for some applications and depending on individual circumstances, it may be beneficial to provide a more thorough implementation by defining an `onHealthCheck` function to the `ApolloServer` constructor options.  If defined, this `onHealthCheck` function should return a `Promise` which _rejects_ if there is an error, or _resolves_ if the server is deemed _ready_.  A `Promise` _rejection_ will result in an HTTP status code of 503, and a _resolution_ will result in an HTTP status code of 200, which is generally desired by most health-check tooling (e.g. Kubernetes, AWS, etc.).
+This basic health check may not be comprehensive enough for some applications and depending on individual circumstances, it may be beneficial to provide a more thorough implementation by defining an `onHealthCheck` function to the `ApolloServer` constructor options. If defined, this `onHealthCheck` async function should return if the server is deemed _ready_ or `throw` if there is an error. Returning (resolving the `Promise`) will result in an HTTP status code of 200, which is generally desired by most health-check tooling (e.g. Kubernetes, AWS, etc.), while `throw`ing (rejecting the `Promise`) will result in an HTTP status code of 503.
 
-> **Note:** Alternatively, the `onHealthCheck` can be defined as an `async` function which `throw`s if it encounters an error and returns when conditions are considered normal.
-
-```js{10-19}
-const { ApolloServer, gql } = require('apollo-server');
+```js{10-17}
+import { ApolloServer, gql } from 'apollo-server';
 
 // Undefined for brevity.
 const typeDefs = gql``;
@@ -19,15 +17,13 @@ const resolvers = {};
 const server = new ApolloServer({
   typeDefs,
   resolvers,
-  onHealthCheck: () => {
-    return new Promise((resolve, reject) => {
-      // Replace the `true` in this conditional with more specific checks!
-      if (true) {
-        resolve();
-      } else {
-        reject();
-      }
-    });
+  async onHealthCheck() {
+    // Replace the `true` in this conditional with more specific checks!
+    if (true) {
+      return;
+    } else {
+      throw new Error('...');
+    }
   },
 });
 

docs/source/performance/caching.md

@@ -6,6 +6,8 @@ description: Configure caching behavior on a per-field basis
 
 > **New in Apollo Server 3**: You must manually define the `@cacheControl` directive in your schema to use static cache hints. [See below.](#in-your-schema-static)
 
+> Note: Apollo Federation doesn't currently support @cacheControl out-of-the-box. There is [an issue](https://github.com/apollographql/federation/issues/356) on the Federation repo which discusses this and proposes possible workarounds.
+
 Apollo Server enables you to define cache control settings (`maxAge` and `scope`) for each field in your schema:
 
 ```graphql{5,7}
@@ -306,7 +308,7 @@ If you run Apollo Server behind a CDN or another caching proxy, you can configur
 
 Because CDNs and caching proxies only cache GET requests (not POST requests, which Apollo Client sends for all operations by default), we recommend enabling [automatic persisted queries](./apq/) and the [`useGETForHashedQueries` option](./apq/) in Apollo Client.
 
-Alternatively, you can set the `useGETForQueries` option of [HttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-http) in your `ApolloClient` instance, but **this is less secure** because your query string and GraphQL variables are sent as plaintext URL query parameters.
+Alternatively, you can set the `useGETForQueries` option of [HttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-http) in your `ApolloClient` instance. However, most browsers enforce a size limit on GET requests, and large query strings might exceed this limit.
 
 ## Disabling cache control
 

docs/source/proxy-configuration.md

@@ -3,20 +3,15 @@ title: Proxy configuration
 description: Configuring proxy settings for outgoing requests
 ---
 
-Certain features of the Apollo platform require Apollo Server to make outgoing requests to Apollo Studio.  These include:
+Certain features of the Apollo platform (such as [managed federation](https://www.apollographql.com/docs/federation/managed-federation/overview/)) require Apollo Server to make outgoing requests to Apollo Studio. Depending on security policies, you might need to configure an outgoing HTTP proxy in order to allow these requests.
 
-* Managed federation
-* Operation registry
+Although Apollo Server supports standard Node.js "agent" configuration via [`https.globalAgent`](https://nodejs.org/api/https.html#https_https_globalagent) and [`http.globalAgent`](https://nodejs.org/api/http.html#http_http_globalagent) directly, we recommend using the [`global-agent`](https://github.com/gajus/global-agent#global-agent) package to reduce the amount of necessary configuration involved with [creating a custom agent](https://nodejs.org/api/http.html#http_class_http_agent).
 
-Depending on security policies, you might need to configure an outgoing HTTP proxy in order to allow these requests.
-
-While Apollo Server supports standard Node.js "agent" configuration via [`https.globalAgent`](https://nodejs.org/api/https.html#https_https_globalagent) and [`http.globalAgent`](https://nodejs.org/api/http.html#http_http_globalagent) directly, we recommend using the [`global-agent`](https://github.com/gajus/global-agent#global-agent) package to reduce the amount of necessary configuration involved with [creating a custom agent](https://nodejs.org/api/http.html#http_class_http_agent).
-
-The `global-agent` package allows support for the common technique of setting proxy settings using environment variables (e.g. `HTTP_PROXY`, `NO_AGENT`, etc.), which is not supported by Node.js itself (and [may never be](https://github.com/nodejs/node/issues/15620)).
+The `global-agent` package enables the common technique of setting proxy settings using environment variables (e.g. `HTTP_PROXY`, `NO_AGENT`, etc.), which is not supported by Node.js itself (and [may never be](https://github.com/nodejs/node/issues/15620)).
 
 ## Configuring the proxy agent
 
-This guide covers the `global-agent` package which is supported by Node.js versions v10 and higher.  When using Node.js versions _prior_ to v10, consider using the [`global-tunnel-ng`](https://github.com/np-maintain/global-tunnel) which behaves similarly, but is configured differently.
+This guide covers the `global-agent` package, which is supported by Node.js version 10 and later.
 
 ### Installing the `global-agent` dependency
 
@@ -98,6 +93,6 @@ This can be done [via Node.js' `NODE_EXTRA_CA_CERTS` environment variable](https
 
    ```shell
    $ NODE_EXTRA_CA_CERTS=/full/path/to/certificate.pem \
-       GLOBAL_AGENT_HTTP_PROXY=http://proxy:3128/ \
-       node index.js
+      GLOBAL_AGENT_HTTP_PROXY=http://proxy:3128/ \
+      node index.js
    ```

docs/source/schema/custom-scalars.md

@@ -12,7 +12,9 @@ To define a custom scalar, add it to your schema like so:
 scalar MyCustomScalar
 ```
 
-Object types in your schema can now contain fields of type `MyCustomScalar`. However, Apollo Server still needs to know how to interact with values of this new scalar type.
+You can now use `MyCustomScalar` in your schema anywhere you can use a default scalar (e.g., as the type of an object field, input type field, or argument).
+
+However, Apollo Server still needs to know how to interact with values of this new scalar type.
 
 ## Defining custom scalar logic
 
@@ -70,13 +72,13 @@ In the example above, the `Date` scalar is represented on the backend by the `Da
 
 ### `parseValue`
 
-The `parseValue` method converts the scalar's `serialize`d JSON value to its back-end representation before it's added to a resolver's `args`.
+The `parseValue` method converts the scalar's JSON value to its back-end representation before it's added to a resolver's `args`.
 
 Apollo Server calls this method when the scalar is provided by a client as a [GraphQL variable](https://graphql.org/learn/queries/#variables) for an argument. (When a scalar is provided as a hard-coded argument in the operation string, [`parseLiteral`](#parseliteral) is called instead.)
 
 ### `parseLiteral`
 
-When an incoming query string includes the scalar as a hard-coded argument value, that value is part of the query document's abstract syntax tree (AST). Apollo Server calls the `parseLiteral` method to convert the value's AST representation (which is always a string) to the scalar's back-end representation.
+When an incoming query string includes the scalar as a hard-coded argument value, that value is part of the query document's abstract syntax tree (AST). Apollo Server calls the `parseLiteral` method to convert the value's AST representation to the scalar's back-end representation.
 
 In [the example above](#example-the-date-scalar), `parseLiteral` converts the AST value from a string to an integer, and _then_ converts from integer to `Date` to match the result of `parseValue`.
 
@@ -120,25 +122,26 @@ const server = new ApolloServer({
 
 In this example, we create a custom scalar called `Odd` that can only contain odd integers:
 
-```js{19-30}
+```js:title=index.js
 const { ApolloServer, gql, UserInputError } = require('apollo-server');
 const { GraphQLScalarType, Kind } = require('graphql');
 
 // Basic schema
 const typeDefs = gql`
   scalar Odd
 
-  type MyType {
-    oddValue: Odd
+  type Query {
+    # Echoes the provided odd integer
+    echoOdd(odd: Odd!): Odd!
   }
 `;
 
-// Validation function
+// Validation function for checking "oddness"
 function oddValue(value) {
-  if (typeof value === "number" && value % 2 === 1) {
+  if (typeof value === "number" && Number.isInteger(value) && value % 2 !== 0) {
     return value;
   }
-  throw new UserInputError("provided value is not an odd number");
+  throw new UserInputError("Provided value is not an odd integer");
 }
 
 const resolvers = {
@@ -151,9 +154,14 @@ const resolvers = {
       if (ast.kind === Kind.INT) {
         return oddValue(parseInt(ast.value, 10));
       }
-      return null;
+      throw new UserInputError("Provided value is not an odd integer");
     },
   }),
+  Query: {
+    echoOdd(_, {odd}) {
+      return odd;
+    }
+  }
 };
 
 const server = new ApolloServer({ typeDefs, resolvers });

docs/source/schema/directives.md

@@ -29,16 +29,37 @@ For example, here's the GraphQL spec's definition of the `@deprecated` directive
 ```graphql
 directive @deprecated(
   reason: String = "No longer supported"
-) on FIELD_DEFINITION | ENUM_VALUE
+) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE
 ```
 
-This indicates that `@deprecated` can decorate either a schema  `FIELD_DEFINITION` (as shown at the top of the article) or a schema `ENUM_VALUE` definition (as shown here):
+This indicates that `@deprecated` can decorate any of the four listed locations. Also note that its `reason` argument is optional and provides a default value. Usage examples of each location are provided below:
 
 ```graphql:title=schema.graphql
+# ARGUMENT_DEFINITION
+# Note: @deprecated arguments _must_ be optional.
+directive @withDeprecatedArgs(
+  deprecatedArg: String @deprecated(reason: "Use `newArg`"),
+  newArg: String
+) on FIELD
+
+type MyType {
+  # ARGUMENT_DEFINITION (alternate example on a field's args)
+  fieldWithDeprecatedArgs(name: String! @deprecated): String
+  # FIELD_DEFINITION
+  deprecatedField: String @deprecated
+}
+
 enum MyEnum {
+  # ENUM_VALUE
   OLD_VALUE @deprecated(reason: "Use `NEW_VALUE`.")
   NEW_VALUE
 }
+
+input SomeInputType {
+  nonDeprecated: String
+  # INPUT_FIELD_DEFINITION
+  deprecated: String @deprecated
+}
 ```
 
 If `@deprecated` appears elsewhere in a GraphQL document, it produces an error.