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

- 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 v17 '@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/index.ts

@@ -508,12 +508,20 @@ export {
   // Create a GraphQLType from a GraphQL language AST.
   typeFromAST,
   // Create a JavaScript value from a GraphQL language AST with a Type.
-  /** @deprecated use `coerceInputLiteral()` instead - will be removed in v18 */
+  /**
+   * Deprecated export retained for compatibility. Use `coerceInputLiteral()`
+   * instead.
+   * @deprecated use `coerceInputLiteral()` instead - will be removed in v18
+   */
   valueFromAST,
   // Create a JavaScript value from a GraphQL language AST without a Type.
   valueFromASTUntyped,
   // Create a GraphQL language AST from a JavaScript value.
-  /** @deprecated use `valueToLiteral()` instead with care to operate on external values - `astFromValue()` will be removed in v18 */
+  /**
+   * Deprecated export retained for compatibility. Use `valueToLiteral()`
+   * instead, and take care to operate on external values.
+   * @deprecated use `valueToLiteral()` instead with care to operate on external values - `astFromValue()` will be removed in v18
+   */
   astFromValue,
   // A helper to use within recursive-descent visitors which need to be aware of the GraphQL type system.
   TypeInfo,

src/language/parser.ts

@@ -104,9 +104,7 @@ export interface ParseOptions {
    * and arguments on fragment spreads. Fragment variable definitions will be represented
    * in the `variableDefinitions` field of the FragmentDefinitionNode.
    * Fragment spread arguments will be represented in the `arguments` field of FragmentSpreadNode.
-   *
-   * For example:
-   *
+   * @example
    * ```graphql
    * {
    *   t { ...A(var: true) }
@@ -123,7 +121,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
    * ```