fix(tspd): document generated auto decorator accessors

Use the decorator's own description so libraries re-exporting the accessors
satisfy api-extractor.

Author: timotheeguerin

.chronus/changes/graphql-regen-auto-accessor-docs-2026-9-2.md

@@ -0,0 +1,8 @@
+---
+changeKind: internal
+packages:
+  - "@typespec/graphql"
+---
+
+Regenerate the decorator signatures to pick up the doc comments now emitted for auto decorator
+accessors.

.chronus/changes/tspd-auto-accessor-docs-2026-9-2.md

@@ -0,0 +1,15 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/tspd"
+---
+
+Document the generated auto decorator accessors with the description of the decorator they read or
+write, so libraries re-exporting them satisfy api-extractor's `ae-undocumented` rule.
+
+```ts
+/** Mark a model as a GraphQL input type in the emitted schema. */
+export function isInputType(program: Program, target: Model): boolean {
+  return hasAutoDecorator(program, "TypeSpec.GraphQL.inputType", target);
+}
+```

packages/graphql/generated-defs/TypeSpec.GraphQL.ts

@@ -184,40 +184,92 @@ export type TypeSpecGraphQLDecorators = {
   specifiedBy: SpecifiedByDecorator;
 };
 
+/**
+ * Mark a model as a GraphQL input type in the emitted schema.
+ *
+ * This decorator is applied automatically by the mutation engine when it produces
+ * a model that is used in input position. The emitter uses this to emit the model
+ * as an `input` type rather than an object `type`.
+ */
 export function isInputType(program: Program, target: Model): boolean {
   return hasAutoDecorator(program, "TypeSpec.GraphQL.inputType", target);
 }
 
+/**
+ * Mark a model as a GraphQL input type in the emitted schema.
+ *
+ * This decorator is applied automatically by the mutation engine when it produces
+ * a model that is used in input position. The emitter uses this to emit the model
+ * as an `input` type rather than an object `type`.
+ */
 export function setInputType(program: Program, target: Model): void {
   setAutoDecorator(program, "TypeSpec.GraphQL.inputType", target);
 }
 
+/**
+ * Mark a field, operation, or type as nullable in the emitted GraphQL schema.
+ *
+ * Applied automatically by the mutation engine when it strips `| null` from
+ * union types, and can also be applied directly in TypeSpec source.
+ */
 export function isNullable(
   program: Program,
   target: ModelProperty | Operation | Union | Model,
 ): boolean {
   return hasAutoDecorator(program, "TypeSpec.GraphQL.nullable", target);
 }
 
+/**
+ * Mark a field, operation, or type as nullable in the emitted GraphQL schema.
+ *
+ * Applied automatically by the mutation engine when it strips `| null` from
+ * union types, and can also be applied directly in TypeSpec source.
+ */
 export function setNullable(
   program: Program,
   target: ModelProperty | Operation | Union | Model,
 ): void {
   setAutoDecorator(program, "TypeSpec.GraphQL.nullable", target);
 }
 
+/**
+ * Mark a field or operation as having nullable array elements in the emitted GraphQL schema.
+ *
+ * Applied automatically by the mutation engine when it detects `Array<T | null>`
+ * patterns. Causes the emitter to emit `[T]` instead of `[T!]`.
+ */
 export function isNullableElements(program: Program, target: ModelProperty | Operation): boolean {
   return hasAutoDecorator(program, "TypeSpec.GraphQL.nullableElements", target);
 }
 
+/**
+ * Mark a field or operation as having nullable array elements in the emitted GraphQL schema.
+ *
+ * Applied automatically by the mutation engine when it detects `Array<T | null>`
+ * patterns. Causes the emitter to emit `[T]` instead of `[T!]`.
+ */
 export function setNullableElements(program: Program, target: ModelProperty | Operation): void {
   setAutoDecorator(program, "TypeSpec.GraphQL.nullableElements", target);
 }
 
+/**
+ * Mark a model as a `@oneOf` input object in the emitted GraphQL schema.
+ *
+ * This decorator is applied automatically by the mutation engine when it converts
+ * a union type in input context to a synthetic input object (since GraphQL unions
+ * are output-only). The emitter uses this to emit the `@oneOf` directive.
+ */
 export function isOneOf(program: Program, target: Model): boolean {
   return hasAutoDecorator(program, "TypeSpec.GraphQL.oneOf", target);
 }
 
+/**
+ * Mark a model as a `@oneOf` input object in the emitted GraphQL schema.
+ *
+ * This decorator is applied automatically by the mutation engine when it converts
+ * a union type in input context to a synthetic input object (since GraphQL unions
+ * are output-only). The emitter uses this to emit the `@oneOf` directive.
+ */
 export function setOneOf(program: Program, target: Model): void {
   setAutoDecorator(program, "TypeSpec.GraphQL.oneOf", target);
 }

packages/tspd/src/gen-extern-signatures/components/auto-decorator-accessors.tsx

@@ -1,5 +1,6 @@
 import { code, For, List } from "@alloy-js/core";
 import * as ts from "@alloy-js/typescript";
+import type { Decorator } from "@typespec/compiler";
 import { typespecCompiler } from "../external-packages/compiler.js";
 import type { DecoratorSignature } from "../types.js";
 import { ParameterTsType, TargetParameterTsType } from "./decorator-signature-type.js";
@@ -51,17 +52,20 @@ function AutoDecoratorReader(props: Readonly<AutoDecoratorAccessorProps>) {
   if (params.length === 0) {
     // No-arg auto decorator — generate `is*` function
     return (
-      <ts.FunctionDeclaration
-        export
-        name={`is${capitalizedName}`}
-        parameters={[
-          { name: "program", type: typespecCompiler.Program },
-          { name: decorator.target.name, type: targetType },
-        ]}
-        returnType="boolean"
-      >
-        {code`return ${typespecCompiler.hasAutoDecorator}(program, "${fqn}", ${decorator.target.name});`}
-      </ts.FunctionDeclaration>
+      <List hardline>
+        <AccessorDoc decorator={decorator} />
+        <ts.FunctionDeclaration
+          export
+          name={`is${capitalizedName}`}
+          parameters={[
+            { name: "program", type: typespecCompiler.Program },
+            { name: decorator.target.name, type: targetType },
+          ]}
+          returnType="boolean"
+        >
+          {code`return ${typespecCompiler.hasAutoDecorator}(program, "${fqn}", ${decorator.target.name});`}
+        </ts.FunctionDeclaration>
+      </List>
     );
   }
 
@@ -99,17 +103,20 @@ function AutoDecoratorReader(props: Readonly<AutoDecoratorAccessorProps>) {
   }
 
   return (
-    <ts.FunctionDeclaration
-      export
-      name={`get${capitalizedName}`}
-      parameters={[
-        { name: "program", type: typespecCompiler.Program },
-        { name: decorator.target.name, type: targetType },
-      ]}
-      returnType={returnType}
-    >
-      {body}
-    </ts.FunctionDeclaration>
+    <List hardline>
+      <AccessorDoc decorator={decorator} />
+      <ts.FunctionDeclaration
+        export
+        name={`get${capitalizedName}`}
+        parameters={[
+          { name: "program", type: typespecCompiler.Program },
+          { name: decorator.target.name, type: targetType },
+        ]}
+        returnType={returnType}
+      >
+        {body}
+      </ts.FunctionDeclaration>
+    </List>
   );
 }
 
@@ -161,13 +168,60 @@ function AutoDecoratorSetter(props: Readonly<AutoDecoratorAccessorProps>) {
   }
 
   return (
-    <ts.FunctionDeclaration
-      export
-      name={`set${capitalizedName}`}
-      parameters={parameters}
-      returnType="void"
-    >
-      {body}
-    </ts.FunctionDeclaration>
+    <List hardline>
+      <AccessorDoc decorator={decorator} />
+      <ts.FunctionDeclaration
+        export
+        name={`set${capitalizedName}`}
+        parameters={parameters}
+        returnType="void"
+      >
+        {body}
+      </ts.FunctionDeclaration>
+    </List>
   );
 }
+
+/**
+ * Render the decorator's own documentation as the accessor doc comment.
+ *
+ * Only the description is carried over: the `@param` tags of the decorator describe its TypeSpec
+ * parameters, which do not line up with the accessor signatures.
+ *
+ * The comment is rendered standalone rather than through the `doc` prop of
+ * `ts.FunctionDeclaration`, because that also emits `@param {Type}` tags whose type references count
+ * as value usages and would turn the type-only imports of this file into value imports.
+ */
+function AccessorDoc(props: Readonly<{ decorator: Decorator }>) {
+  const description = getDocDescription(props.decorator);
+  if (description === undefined) {
+    return null;
+  }
+  const lines = description.split("\n");
+  const comment =
+    lines.length === 1
+      ? `/** ${lines[0]} */`
+      : [`/**`, ...lines.map((line) => ` * ${line}`.trimEnd()), ` */`].join("\n");
+  return <>{comment}</>;
+}
+
+/** Get the description of a decorator, excluding any doc tag. */
+function getDocDescription(decorator: Decorator): string | undefined {
+  const docs = decorator.node?.docs;
+  if (docs === undefined || docs.length === 0) {
+    return undefined;
+  }
+
+  const lines: string[] = [];
+  for (const doc of docs) {
+    for (const content of doc.content) {
+      for (const line of content.text.split("\n")) {
+        // Issue to escape @internal and other tsdoc tags https://github.com/microsoft/TypeScript/issues/47679
+        lines.push(line.replaceAll("@internal", "@_internal"));
+      }
+    }
+  }
+
+  const description = lines.join("\n").trim();
+  return description === "" ? undefined : description;
+}

packages/tspd/test/gen-extern-signature/decorators-signatures.test.ts

@@ -531,6 +531,49 @@ export function setMyMeta(program: Program, target: Model, value: { name: string
     });
   });
 
+  it("documents accessors with the decorator description, dropping doc tags", async () => {
+    await expectSignatures({
+      code: `
+        /**
+         * Specify the minimum number of instances the array must contain.
+         *
+         * @param value The minimum number of instances.
+         */
+        auto dec myMin(target: Model, value: valueof int32);
+      `,
+      expected: `
+import { getAutoDecoratorValue, type Model, type Program, setAutoDecorator } from "@typespec/compiler";
+
+/** Specify the minimum number of instances the array must contain. */
+export function getMyMin(program: Program, target: Model): number | undefined {
+  return getAutoDecoratorValue(program, "myMin", target)?.["value"] as any;
+}
+
+/** Specify the minimum number of instances the array must contain. */
+export function setMyMin(program: Program, target: Model, value: number): void {
+  setAutoDecorator(program, "myMin", target, { value: value });
+}
+  `,
+    });
+  });
+
+  it("renders a multi line description as a block comment", async () => {
+    const result = await generateDecoratorSignatures(`
+      /**
+       * First line.
+       *
+       * Second line.
+       */
+      auto dec myFlag(target: Model);
+    `);
+    expect(result).toContain(`/**
+ * First line.
+ *
+ * Second line.
+ */
+export function isMyFlag`);
+  });
+
   it("generates accessor with fully-qualified name for namespaced auto decorator", async () => {
     const [{ program }] = await Tester.compileAndDiagnose(
       `