Add documentation rules to the library linter

[timotheeguerin]

Nothing today stops a library from publishing an undocumented declaration — the only signal is tspd's documentation-missing, which runs during regen-docs, reports with no file or line, and is not build-breaking. Nothing at all catches a doc comment that documents something that does not exist.

Two rules in @typespec/library-linter, reported against the offending declaration so the squiggle lands in the right place:

missing-documentation — a public declaration or member has no doc comment and no @doc. Covers models, enums, unions, scalars, interfaces, operations and decorators, plus their members: properties, enum members, union variants, operation and decorator parameters, and template parameters. @param/@prop on the container counts as documenting the member. Anything in a Private namespace or marked internal is skipped.

extraneous-documentation — a doc comment documents something that is not there:

/**
 * @param blah Does not exist.                            // no such parameter
 * @template Resource The resource model.                 // belongs to the enclosing interface
 * @returns ...                                           // only operations return
 * Resource marked with @resource                         // unescaped code read as a tag
 */

That last one is the common case and it is not cosmetic: the parser treats everything after the bogus tag as tag content, so the description is silently truncated on the published page. This is how protobuf ended up shipping a bullet that reads - not fall within any range that was [marked reserved](#.

Merge last

lint-typespec-library already runs with --warn-as-error in every library's build, so these rules are enforced the moment this merges. CI on this PR stays red until all four documentation PRs land, which fix the 97 real violations these rules found:

• Document public declarations in @typespec/http #11539 — http
• Document Format enum members in @typespec/json-schema #11540 — json-schema
• Fix doc comments that document things that don't exist in @typespec/rest #11541 — rest
• Document remaining public declarations across the smaller libraries #11542 — protobuf, graphql, events, http-client

Those four are independent of each other and of this PR, and can merge in any order. This one goes last.

Fixes #1229
Fixes #2090

[Copilot]

Pull request overview

Adds documentation validation to @typespec/library-linter so libraries can’t publish undocumented public API surface or doc comments that reference non-existent members/tags, with diagnostics reported on the relevant declarations for accurate editor squiggles.

Changes:

• Add missing-documentation and extraneous-documentation diagnostics to the library-linter ruleset and wire them into $onValidate.
• Implement documentation analysis over public library declarations/members, including handling of decorator docs and template-related traversal.
• Add/adjust tests and documentation (README + Chronus entry) to cover and describe the new rules.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/library-linter/src/validate-docs.ts	Implements the new documentation validation logic and diagnostic reporting.
packages/library-linter/src/linter.ts	Hooks documentation validation into the library-linter validate pass.
packages/library-linter/src/lib.ts	Registers the new diagnostic codes and message templates.
packages/library-linter/test/validate-docs.test.ts	Adds unit tests covering missing/extraneous documentation scenarios.
packages/library-linter/test/linter.test.ts	Updates existing tests to include docs so they don’t fail under the new rules.
packages/library-linter/README.md	Documents the new linter rules and their intent.
.chronus/changes/library-linter-doc-validation-2026-8-11.md	Adds changelog entry for the new rules.

[timotheeguerin]

Good catch — fixed in 933cd3f.

checkMember now always runs checkDocTags on the member's own doc comment instead of returning early once the member is documented. Members support no structured tags of their own (no params, props or template parameters, and only operations return), so anything but a known freeform tag is now reported.

This surfaced a real bug in @typespec/http: PatchOptions.implicitOptionality used an @deprecated doc tag, which TypeSpec doesn't recognise (#deprecated is a directive, not a doc tag), so the whole deprecation notice was silently dropped from the published reference docs — the rendered text stopped at "...deeply optional." and the migration guidance never appeared. Fixed in #11539.

Added three regression tests (unknown tag on a property, @returns on a property, unknown tag on an enum member).

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/library-linter@11543

commit: 65515f2

[github-actions]

All changed packages have been documented.

• ✅ @typespec/library-linter

Show changes

@typespec/library-linter - feature ✏️

Add missing-documentation and extraneous-documentation rules,> ,> missing-documentation reports public declarations and members of a library that have no doc,> comment or @doc, so gaps in the generated reference documentation are caught at build time.,> ,> extraneous-documentation reports doc comments that document something that doesn't exist, such as,> a @param naming a parameter the operation doesn't have, a @template copied from an enclosing,> interface, or an unescaped code reference the parser mistook for a tag:,> ,> typespec,> /**,> * Creates or updates an instance of the resource.,> * @template Resource The resource model. // `create` is not templated: the interface is,> */,> create(resource: Resource): Resource;,> ,> ,> Declarations in a Private namespace and declarations marked internal are excluded.