Document public declarations in @typespec/http

[timotheeguerin]

Several public declarations in @typespec/http ship with no documentation at all, so they render as blank rows in the reference docs: HttpPart, Link, LinkHeader, HttpPartOptions, PathOptions, @multipartBody, and the template parameters of HttpPart/LinkHeader.

This fills those in.

It also fixes a doc comment that documents a parameter that does not exist:

/**
 * @param uriTemplate Uri template for this operation.   // the parameter is named `path`
 */
extern dec route(target: Namespace | Interface | Operation, path: valueof string);

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 (#11540, #11541, #11542) — they touch disjoint packages and can merge in any order.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/http@11539

commit: a0c93ed

[github-actions]

All changed packages have been documented.

• ✅ @typespec/http

Show changes

@typespec/http - internal ✏️

Add missing documentation to public declarations and fix the @route @param name

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

[Copilot]

Pull request overview

Improves the public API documentation for @typespec/http so reference docs no longer show blank entries for key HTTP multipart/link types and decorators, and fixes an incorrect @route parameter name in doc comments (to align with path).

Changes:

• Add/expand documentation for HttpPart, HttpPartOptions, Link, LinkHeader, PathOptions, and @multipartBody (library source + rendered docs).
• Fix @route doc comment parameter name from uriTemplate to path (and update the rendered parameter tables).
• Add a Chronus entry for the documentation update.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
website/src/content/docs/docs/libraries/http/reference/decorators.md	Adds @multipartBody description and fixes @route parameter table description.
website/src/content/docs/docs/libraries/http/reference/data-types.md	Fills in missing docs for HttpPart, HttpPartOptions, Link, LinkHeader, and related property/template parameter descriptions (plus example).
packages/http/README.md	Mirrors reference-doc improvements for @multipartBody and @route parameter table.
packages/http/lib/main.tsp	Adds doc comments/examples for HttpPartOptions, HttpPart, Link, LinkHeader.
packages/http/lib/decorators.tsp	Adds PathOptions docs, expands @multipartBody docs, and corrects @route @param name.
packages/http/lib/auth.tsp	Adds missing property-level doc for NoAuth.type.
packages/http/generated-defs/TypeSpec.Http.ts	Regenerates/updates the TS declarations docblocks to match the new TypeSpec docs (e.g., @multipartBody, @route).
.chronus/changes/docs-http-2026-8-11.md	Adds a Chronus entry for the documentation updates.

[timotheeguerin]

Addressed both review comments in 810cc57:

• Model expression separators — switched the HttpPart example to ; between model properties and , between operation parameters, matching what the TypeSpec formatter produces. Also applied the same fix to the pre-existing @multipartBody example in decorators.tsp, which had the same inconsistency, so the two examples now agree.
• URI casing — normalised all occurrences in decorators.tsp to URI template, matching the existing @route wording.

Also picked up one extra fix here, surfaced by the reviewer feedback on #11543: PatchOptions.implicitOptionality documented its deprecation with an @deprecated doc tag. TypeSpec has no such doc tag (#deprecated is a directive), so the parser treated it as an unknown tag and the entire notice was dropped from the generated docs — data-types.md rendered only "...deeply optional." and none of the migration guidance. Rewritten as prose so it renders.