Fix doc comments that document things that don't exist in @typespec/rest

[timotheeguerin]

This is the package that motivated #2090.

Every operation inside the resource interface templates carries a copy of its enclosing interface's @template tags, documenting template parameters the operation does not have:

interface ResourceCreateOrUpdate<Resource extends {}, Error> {
  /**
   * Creates or update an instance of the resource.
   *
   * @template Resource The resource model to create or update.   // `createOrUpdate` is not templated
   * @template Error The error response.                          // neither is this
   */
  createOrUpdate(...): ...;
}

29 of these are removed.

rest-decorators.tsp has the other flavour of the bug — code references the doc parser mistakes for tags, which truncate the published text:

 * Defines the preceding path segment for a @path parameter in auto-generated routes.
 * @param resourceType Resource marked with @resource

These are now backticked, and the @segment example gets the ```typespec fence it was missing.

The remaining change documents the request body parameters (resource, properties) of the resource operation templates.

Prerequisite for #1229 and #2090. The library linter rule that catches this is in #11543, which must merge after this one: lint-typespec-library runs with --warn-as-error inside every package's build, so the docs have to exist before the rule is turned on.

Independent of the other documentation PRs (#11539, #11540, #11542) — they touch disjoint packages and can merge in any order.

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/rest@11541

commit: c1ecc9d

[github-actions]

All changed packages have been documented.

• ✅ @typespec/rest

Show changes

@typespec/rest - internal ✏️

Remove doc comment @template tags that referenced the enclosing interface, and document the remaining operation body parameters

[timotheeguerin]

Fixed the description bleed in c1ecc9d.

Documenting the body parameters gave them a real doc, and openapi3 reads getDoc on the body property to build requestBody.description — so every downstream spec using ResourceCreateOrReplace, ResourceCreateOrUpdate, ResourceCreate or ResourceUpdate suddenly grew a description: The properties of the resource to create. it never asked for. That's what broke @typespec/samples (6 snapshot failures).

Added @doc("") alongside each of the 8 body-parameter doc comments. The doc comment still satisfies the linter and still shows up in the generated reference docs, but @doc takes precedence for getDoc, and openapi3 guards with if (desc), so nothing is emitted. This matches the existing convention in resource.tsp, where the operations already pair a doc comment with an explicit @doc(...).

Verified by emitting OpenAPI for a spec built on ResourceCreateOrReplace and diffing against main — byte-identical. @typespec/samples is back to 58/58 with no snapshot updates, and rest (63) and openapi3 (2576) pass. Also re-ran the samples suite on the other three docs branches to confirm none of them shift emitted output.

Rebased onto latest main.