docs: fix inline examples, deprecation descriptions, type category (#4757)

- Move public documentation sample blocks out of descriptions and into `@example` tags, including root package, parser option, type, schema, astFromValue, and stripIgnoredCharacters docs.
- Update every public v16 `@deprecated` JSDoc block so the prose itself says the API is deprecated and points users to the replacement or migration path.
- Rename the graphql/type Definitions JSDoc category to Types so the generated API docs use the clearer category name.

Author: yaacovCR

src/error/GraphQLError.ts

@@ -136,6 +136,8 @@ export class GraphQLError extends Error {
    * Creates a GraphQLError instance.
    * @param message - Human-readable error message.
    * @param options - Error metadata such as source locations, response path, original error, and extensions.
+   * This positional-arguments constructor overload is deprecated. Use the
+   * `GraphQLError(message, options)` overload instead.
    * @example
    * ```ts
    * // Create an error from AST nodes and response metadata.
@@ -178,8 +180,9 @@ export class GraphQLError extends Error {
   constructor(message: string, options?: GraphQLErrorOptions);
   /**
    * Creates a GraphQLError instance using the legacy positional constructor.
-   * Prefer the `GraphQLErrorOptions` object overload, which keeps optional error
-   * metadata in a single options bag.
+   * This deprecated overload will be removed in v17. Prefer the
+   * `GraphQLErrorOptions` object overload, which keeps optional error metadata
+   * in a single options bag.
    * @param message - Human-readable error message.
    * @param nodes - AST node or nodes associated with this error.
    * @param source - Source document used to derive error locations.
@@ -409,9 +412,9 @@ export interface GraphQLFormattedError {
 
 /**
  * Prints a GraphQLError to a string, representing useful location information
- * about the error's position in the source. This helper is retained for
- * backwards compatibility; call `error.toString()` instead because printError
- * will be removed in v17.
+ * about the error's position in the source. This deprecated helper is retained
+ * for backwards compatibility; call `error.toString()` instead because
+ * printError will be removed in v17.
  * @param error - The error to format.
  * @returns The printed string representation.
  * @example
@@ -430,9 +433,9 @@ export function printError(error: GraphQLError): string {
 
 /**
  * Given a GraphQLError, format it according to the rules described by the
- * Response Format, Errors section of the GraphQL Specification. This helper is
- * retained for backwards compatibility; call `error.toJSON()` instead because
- * formatError will be removed in v17.
+ * Response Format, Errors section of the GraphQL Specification. This deprecated
+ * helper is retained for backwards compatibility; call `error.toJSON()`
+ * instead because formatError will be removed in v17.
  * @param error - The error to format.
  * @returns The JSON-serializable formatted error.
  * @example

src/execution/execute.ts

@@ -481,7 +481,9 @@ function buildResponse(
 
 /**
  * Essential assertions before executing to provide developer feedback for
- * improper use of the GraphQL library.
+ * improper use of the GraphQL library. This deprecated internal helper will be
+ * removed in v17; call `assertValidSchema()` and rely on TypeScript checks
+ * instead.
  *
  * @deprecated will be removed in v17 in favor of assertValidSchema() and TS checks
  * @internal

src/execution/subscribe.ts

@@ -284,8 +284,8 @@ export async function createSourceEventStream(
 ): Promise<AsyncIterable<unknown> | ExecutionResult>;
 /**
  * Creates the source event stream for a subscription operation using the legacy
- * positional argument overload. Use the args object overload instead; this
- * overload will be removed in the next major version.
+ * positional argument overload. This deprecated overload will be removed in the
+ * next major version; use the args object overload instead.
  * @param schema - GraphQL schema to use.
  * @param document - The parsed GraphQL document containing the subscription
  * operation.

src/language/ast.ts

@@ -552,7 +552,11 @@ export interface FragmentDefinitionNode {
   /** Name node identifying this AST node. */
   readonly name: NameNode;
   /**
-   * Variable definitions declared by this legacy fragment definition.
+   * Deprecated variable definitions declared by this legacy fragment
+   * definition. This legacy fragment variable syntax will be removed in v17.
+   * Move variable definitions to operations for spec-compliant documents; if
+   * you need variables or arguments scoped to fragments, v17 has a more
+   * complete experimental fragment-arguments feature.
    * @deprecated variableDefinitions will be removed in v17.0.0
    */
   readonly variableDefinitions?: ReadonlyArray<VariableDefinitionNode>;

src/language/directiveLocation.ts

@@ -46,9 +46,11 @@ enum DirectiveLocation {
 export { DirectiveLocation };
 
 /**
- * Legacy alias for the enum type representing directive location values. This
- * is retained for backwards compatibility; use `DirectiveLocation` instead
- * because DirectiveLocationEnum will be removed in v17.
- * @deprecated Please use `DirectiveLocation`. Will be removed in v17.
+ * Deprecated legacy alias for the enum type representing directive location
+ * values. This alias will be removed in v17. In v17, `DirectiveLocation` is
+ * exported as the single public symbol for both the runtime object and the
+ * corresponding TypeScript type.
+ * @deprecated Will be removed in v17. In v17, use `DirectiveLocation` as both
+ * the runtime value and the type.
  */
 export type DirectiveLocationEnum = typeof DirectiveLocation;

src/language/kinds.ts

@@ -115,9 +115,11 @@ enum Kind {
 export { Kind };
 
 /**
- * Legacy alias for the enum type representing the possible kind values of AST
- * nodes. This is retained for backwards compatibility; use `Kind` instead
- * because KindEnum will be removed in v17.
- * @deprecated Please use `Kind`. Will be removed in v17.
+ * Deprecated legacy alias for the enum type representing the possible kind
+ * values of AST nodes. This alias will be removed in v17. In v17, `Kind` is
+ * exported as the single public symbol for both the runtime object and the
+ * corresponding TypeScript type.
+ * @deprecated Will be removed in v17. In v17, use `Kind` as both the runtime
+ * value and the type.
  */
 export type KindEnum = typeof Kind;

src/language/parser.ts

@@ -97,20 +97,24 @@ export interface ParseOptions {
   maxTokens?: number | undefined;
 
   /**
-   * Allows legacy fragment variable definitions to be parsed.
-   * @deprecated will be removed in the v17.0.0
-   *
-   * If enabled, the parser will understand and parse variable definitions
-   * contained in a fragment definition. They'll be represented in the
-   * `variableDefinitions` field of the FragmentDefinitionNode.
-   *
-   * The syntax is identical to normal, query-defined variables. For example:
+   * Deprecated option that allows legacy fragment variable definitions to be
+   * parsed. This legacy fragment variable syntax will be removed in v17. Move
+   * variable definitions to operations for spec-compliant documents; if you
+   * need variables or arguments scoped to fragments, v17 has a more complete
+   * experimental fragment-arguments feature.
+   * @example
+   * The syntax is identical to normal, query-defined variables.
    *
    * ```graphql
    * fragment A($var: Boolean = false) on T {
    *   ...
    * }
    * ```
+   * @deprecated will be removed in the v17.0.0
+   *
+   * If enabled, the parser will understand and parse variable definitions
+   * contained in a fragment definition. They'll be represented in the
+   * `variableDefinitions` field of the FragmentDefinitionNode.
    */
   allowLegacyFragmentVariables?: boolean;
 
@@ -119,7 +123,7 @@ export interface ParseOptions {
    *
    * If enabled, the parser will parse directives on directive definitions.
    * This syntax is not part of the GraphQL specification and may change.
-   *
+   * @example
    * ```graphql
    * directive @foo @bar on FIELD
    * ```

src/language/tokenKind.ts

@@ -55,9 +55,11 @@ enum TokenKind {
 export { TokenKind };
 
 /**
- * Legacy alias for the enum type representing token kind values. This is
- * retained for backwards compatibility; use `TokenKind` instead because
- * TokenKindEnum will be removed in v17.
- * @deprecated Please use `TokenKind`. Will be removed in v17.
+ * Deprecated legacy alias for the enum type representing token kind values.
+ * This alias will be removed in v17. In v17, `TokenKind` is exported as the
+ * single public symbol for both the runtime object and the corresponding
+ * TypeScript type.
+ * @deprecated Will be removed in v17. In v17, use `TokenKind` as both the
+ * runtime value and the type.
  */
 export type TokenKindEnum = typeof TokenKind;

src/language/visitor.ts

@@ -91,8 +91,8 @@ type ReducedField<T, R> = T extends null | undefined
   : R;
 
 /**
- * Legacy visitor key map type retained for compatibility. Inline this mapped
- * type at use sites; ASTVisitorKeyMap will be removed in v17.
+ * Deprecated visitor key map type retained for compatibility. Inline this
+ * mapped type at use sites because ASTVisitorKeyMap will be removed in v17.
  * @deprecated Please inline it. Will be removed in v17
  */
 export type ASTVisitorKeyMap = {
@@ -508,9 +508,9 @@ export function getEnterLeaveForKind(
 
 /**
  * Given a visitor instance, if it is leaving or not, and a node kind, return
- * the function the visitor runtime should call. This compatibility helper
- * delegates to `getEnterLeaveForKind`; call `getEnterLeaveForKind` directly
- * because getVisitFn will be removed in v17.
+ * the function the visitor runtime should call. This deprecated compatibility
+ * helper delegates to `getEnterLeaveForKind`; call `getEnterLeaveForKind`
+ * directly because getVisitFn will be removed in v17.
  * @param visitor - The visitor object to inspect.
  * @param kind - The AST node kind to resolve a handler for.
  * @param isLeaving - Whether to resolve the leave handler instead of the enter handler.

src/subscription/index.ts

@@ -15,9 +15,9 @@
 import type { ExecutionArgs } from '../execution/execute';
 
 /**
- * Legacy alias for ExecutionArgs retained by the subscription module. Use
- * `ExecutionArgs` directly instead because SubscriptionArgs will be removed in
- * v17.
+ * Deprecated legacy alias for ExecutionArgs retained by the subscription
+ * module. Use `ExecutionArgs` directly instead because SubscriptionArgs will be
+ * removed in v17.
  *
  * ExecutionArgs has been broadened to include all properties within SubscriptionArgs.
  * The SubscriptionArgs type is retained for backwards compatibility.