Solve some low hanging fruit in the documentation

website/pages/execution.mdx

@@ -40,10 +40,14 @@ export function execute(
 
 type MaybePromise<T> = Promise<T> | T;
 
-type ExecutionResult = {
-  data: Object;
-  errors?: GraphQLError[];
-};
+interface ExecutionResult<
+  TData = ObjMap<unknown>,
+  TExtensions = ObjMap<unknown>,
+> {
+  errors?: ReadonlyArray<GraphQLError>;
+  data?: TData | null;
+  extensions?: TExtensions;
+}
 ```
 
 Implements the "Evaluating requests" section of the GraphQL specification.
@@ -56,3 +60,25 @@ a GraphQLError will be thrown immediately explaining the invalid input.
 `ExecutionResult` represents the result of execution. `data` is the result of
 executing the query, `errors` is null if no errors occurred, and is a
 non-empty array if an error occurred.
+
+### executeSync
+
+```ts
+export function executeSync(
+  schema: GraphQLSchema,
+  documentAST: Document,
+  rootValue?: mixed,
+  contextValue?: mixed,
+  variableValues?: { [key: string]: mixed },
+  operationName?: string,
+): ExecutionResult;
+
+type ExecutionResult = {
+  data: Object;
+  errors?: GraphQLError[];
+};
+```
+
+This is a short-hand method that will call `execute` and when the response can
+be returned synchronously it will be returned, when a `Promise` is returned this
+method will throw an error.

website/pages/graphql.mdx

@@ -144,6 +144,15 @@ function graphql(
   variableValues?: { [key: string]: any },
   operationName?: string,
 ): Promise<GraphQLResult>;
+
+interface ExecutionResult<
+  TData = ObjMap<unknown>,
+  TExtensions = ObjMap<unknown>,
+> {
+  errors?: ReadonlyArray<GraphQLError>;
+  data?: TData | null;
+  extensions?: TExtensions;
+}
 ```
 
 The `graphql` function lexes, parses, validates and executes a GraphQL request.

website/pages/type.mdx

@@ -188,16 +188,20 @@ const MyAppSchema = new GraphQLSchema({
 ### GraphQLScalarType
 
 ```ts
-class GraphQLScalarType<InternalType> {
-  constructor(config: GraphQLScalarTypeConfig<InternalType>);
+class GraphQLScalarType<InternalType, ExternalType> {
+  constructor(config: GraphQLScalarTypeConfig<InternalType, ExternalType>);
 }
 
-type GraphQLScalarTypeConfig<InternalType> = {
+type GraphQLScalarTypeConfig<InternalType, ExternalType> = {
   name: string;
   description?: string;
-  serialize: (value: mixed) => InternalType;
-  parseValue?: (value: mixed) => InternalType;
-  parseLiteral?: (valueAST: Value) => InternalType;
+  specifiedByURL?: Maybe<string>;
+  serialize: (outputValue: unknown) => ExternalType;
+  parseValue?: (inputValue: unknown) => InternalType;
+  parseLiteral?: (
+    valueAST: Value,
+    variables?: Maybe<Record<string, unknown>>,
+  ) => InternalType;
 };
 ```
 
@@ -210,19 +214,30 @@ functions used to ensure validity.
 ```js
 const OddType = new GraphQLScalarType({
   name: 'Odd',
-  serialize: oddValue,
-  parseValue: oddValue,
+  // Can be used to link to a specification
+  // for this scalar, for instance the JSON
+  // specification.
+  specifiedByURL: '',
+  description:
+    'This custom scalar will only return a value if the passed in value is an odd integer, when it's not it will return null.'
+  serialize: (outputValue) => {
+    // This function gets called for response-data, the application returns data
+    // for a property and in the schema we see that this value has the "Odd" type.
+   return typeof outputValue === 'number' && outputValue % 2 === 1 ? value : null;
+  },
+  parseValue: (inputValue) => {
+    // This function gets called for input-data, i.e. variables being passed in
+    return typeof inputValue === 'number' && outputValue % 2 === 1 ? value : null;
+  },
   parseLiteral(ast) {
+    // This function gets called when the value is passed in as a literal on the
+    // Executable GraphQL Document
     if (ast.kind === Kind.INT) {
       return oddValue(parseInt(ast.value, 10));
     }
     return null;
   },
 });
-
-function oddValue(value) {
-  return value % 2 === 1 ? value : null;
-}
 ```
 
 ### GraphQLObjectType