docs(diagnostics): document tracing public API

Author: yaacovCR

src/diagnostics.ts

@@ -9,6 +9,7 @@
  * APMs do not need to interact with the graphql API to enable tracing. On
  * runtimes that do not expose `node:diagnostics_channel` (e.g., browsers) the
  * load silently no-ops and emission sites short-circuit.
+ * @category Diagnostics
  */
 
 import { isPromise } from './jsutils/isPromise.ts';
@@ -82,45 +83,67 @@ interface DiagnosticsChannelModule {
  * Context published on `graphql:parse`.
  */
 export interface GraphQLParseContext {
+  /** Source text or source object passed to the parser. */
   source: string | Source;
+  /** Error thrown while parsing, when parsing fails. */
   error?: unknown;
+  /** Parsed document, when parsing succeeds. */
   result?: DocumentNode;
 }
 
 /**
  * Context published on `graphql:validate`.
  */
 export interface GraphQLValidateContext {
+  /** Schema used for validation. */
   schema: GraphQLSchema;
+  /** Parsed document being validated. */
   document: DocumentNode;
+  /** Error thrown while validating, when validation fails abruptly. */
   error?: unknown;
+  /** Validation errors returned by validation. */
   result?: ReadonlyArray<GraphQLError>;
 }
 
 /**
  * Context published on `graphql:execute`.
  */
 export interface GraphQLExecuteContext {
+  /** Schema used for execution. */
   schema: GraphQLSchema;
+  /** Parsed document being executed. */
   document: DocumentNode;
+  /** Raw variable values provided by the caller before coercion. */
   variableValues: Maybe<{ readonly [variable: string]: unknown }>;
+  /** Selected operation name, if one is available. */
   operationName: string | undefined;
+  /** Selected operation type, if one is available. */
   operationType: OperationTypeNode | undefined;
+  /** Error thrown while executing, when execution fails abruptly. */
   error?: unknown;
+  /** Execution result returned by execution. */
   result?: ExecutionResult | ExperimentalIncrementalExecutionResults;
 }
 
 /**
  * Context published on `graphql:execute:rootSelectionSet`.
  */
 export interface GraphQLExecuteRootSelectionSetContext {
+  /** Schema used for execution. */
   schema: GraphQLSchema;
+  /** Parsed document being executed. */
   document: DocumentNode;
+  /** Operation definition selected for execution. */
   operation: OperationDefinitionNode;
+  /** Raw variable values provided by the caller before coercion. */
   variableValues: Maybe<{ readonly [variable: string]: unknown }>;
+  /** Selected operation name, if one is available. */
   operationName: string | undefined;
+  /** Selected operation type. */
   operationType: OperationTypeNode;
+  /** Error thrown while executing the root selection set. */
   error?: unknown;
+  /** Execution result returned from the root selection set. */
   result?: ExecutionResult | ExperimentalIncrementalExecutionResults;
 }
 
@@ -133,13 +156,21 @@ export interface GraphQLExecuteRootSelectionSetContext {
  * carries the `errors` array, mirroring `graphql:validate`.
  */
 export interface GraphQLExecuteVariableCoercionContext {
+  /** Schema used for variable coercion. */
   schema: GraphQLSchema;
+  /** Parsed document being executed. */
   document: DocumentNode;
+  /** Operation definition whose variables are being coerced. */
   operation: OperationDefinitionNode;
+  /** Raw variable values provided by the caller before coercion. */
   rawVariableValues: Maybe<{ readonly [variable: string]: unknown }>;
+  /** Selected operation name, if one is available. */
   operationName: string | undefined;
+  /** Selected operation type. */
   operationType: OperationTypeNode;
+  /** Error thrown while coercing variables, when coercion fails abruptly. */
   error?: unknown;
+  /** Coerced variable values or coercion errors returned by coercion. */
   result?:
     | { variableValues: VariableValues }
     | { errors: ReadonlyArray<GraphQLError> };
@@ -149,37 +180,63 @@ export interface GraphQLExecuteVariableCoercionContext {
  * Context published on `graphql:subscribe`.
  */
 export interface GraphQLSubscribeContext {
+  /** Schema used for subscription execution. */
   schema: GraphQLSchema;
+  /** Parsed subscription document. */
   document: DocumentNode;
+  /** Raw variable values provided by the caller before coercion. */
   variableValues: Maybe<{ readonly [variable: string]: unknown }>;
+  /** Selected operation name, if one is available. */
   operationName: string | undefined;
+  /** Selected operation type, if one is available. */
   operationType: OperationTypeNode | undefined;
+  /** Error thrown while subscribing, when subscription setup fails abruptly. */
   error?: unknown;
+  /** Subscription response stream or execution result returned by subscribe. */
   result?: AsyncGenerator<ExecutionResult, void, void> | ExecutionResult;
 }
 
 /**
  * Context published on `graphql:resolve`.
  */
 export interface GraphQLResolveContext {
+  /** Field name being resolved. */
   fieldName: string;
+  /** Response alias for the field being resolved. */
   alias: string;
+  /** Parent type name for the field being resolved. */
   parentType: string;
+  /** Return type string for the field being resolved. */
   fieldType: string;
+  /** Argument values passed to the resolver. */
   args: ObjMap<unknown>;
+  /** Whether the field is using the default resolver. */
   isDefaultResolver: boolean;
+  /** Response path for the field being resolved. */
   fieldPath: string;
+  /** Error thrown by the resolver, when resolution fails. */
   error?: unknown;
+  /** Value returned by the resolver. */
   result?: unknown;
 }
 
+/**
+ * Mapping from tracing channel name to the context type published on it.
+ */
 export interface GraphQLChannelContextByName {
+  /** Context published on `graphql:parse`. */
   'graphql:parse': GraphQLParseContext;
+  /** Context published on `graphql:validate`. */
   'graphql:validate': GraphQLValidateContext;
+  /** Context published on `graphql:execute`. */
   'graphql:execute': GraphQLExecuteContext;
+  /** Context published on `graphql:execute:variableCoercion`. */
   'graphql:execute:variableCoercion': GraphQLExecuteVariableCoercionContext;
+  /** Context published on `graphql:execute:rootSelectionSet`. */
   'graphql:execute:rootSelectionSet': GraphQLExecuteRootSelectionSetContext;
+  /** Context published on `graphql:subscribe`. */
   'graphql:subscribe': GraphQLSubscribeContext;
+  /** Context published on `graphql:resolve`. */
   'graphql:resolve': GraphQLResolveContext;
 }
 
@@ -190,12 +247,19 @@ export interface GraphQLChannelContextByName {
  * by name.
  */
 export interface GraphQLChannels {
+  /** Tracing channel for `graphql:execute`. */
   execute: MinimalTracingChannel<GraphQLExecuteContext>;
+  /** Tracing channel for `graphql:execute:variableCoercion`. */
   executeVariableCoercion: MinimalTracingChannel<GraphQLExecuteVariableCoercionContext>;
+  /** Tracing channel for `graphql:execute:rootSelectionSet`. */
   executeRootSelectionSet: MinimalTracingChannel<GraphQLExecuteRootSelectionSetContext>;
+  /** Tracing channel for `graphql:parse`. */
   parse: MinimalTracingChannel<GraphQLParseContext>;
+  /** Tracing channel for `graphql:validate`. */
   validate: MinimalTracingChannel<GraphQLValidateContext>;
+  /** Tracing channel for `graphql:resolve`. */
   resolve: MinimalTracingChannel<GraphQLResolveContext>;
+  /** Tracing channel for `graphql:subscribe`. */
   subscribe: MinimalTracingChannel<GraphQLSubscribeContext>;
 }
 

src/execution/Executor.ts

@@ -267,6 +267,7 @@ export class Executor<
    * Build an operation-scoped diagnostics context from ValidatedExecutionArgs.
    * Used after the operation has already been resolved during argument
    * validation.
+   * @internal
    */
   buildExecuteContextFromValidatedArgs(
     args: ValidatedExecutionArgs,
@@ -676,6 +677,7 @@ export class Executor<
    * `fieldPath` is exposed as a lazy getter because serializing the response
    * path is O(depth) and APMs that depth-filter or skip default resolvers
    * often never read it. `args` is passed through by reference.
+   * @internal
    */
   buildResolveContext(
     args: ObjMap<unknown>,

src/execution/execute.ts

@@ -123,6 +123,7 @@ export function execute(args: ExecutionArgs): PromiseOrValue<ExecutionResult> {
  * Build a graphql:execute channel context from raw ExecutionArgs. Defers
  * resolution of the operation AST to a lazy getter so the cost of walking
  * the document is only paid if a subscriber reads it.
+ * @internal
  */
 function buildOperationContextFromArgs(
   args: ExecutionArgs,