Document public API surface ahead of the library-linter documentation rules - #5183
Merged
Timothee Guerin (timotheeguerin) merged 7 commits intoAug 7, 2026
Conversation
The library-linter is gaining missing-documentation and extraneous-documentation rules. Document the public declarations and members that were undocumented, and drop doc tags referencing template parameters that no longer exist.
microsoft-github-policy-service
Bot
added
lib:azure-core
Contributor
|
All changed packages have been documented.
Show changes
|
commit: |
Contributor
📦 Package size report5 packages changed size compared to the base branch.
40 unchanged package(s)
Packed = gzipped |
Contributor
|
You can try these changes here
|
Timothee Guerin (timotheeguerin)
added
the
int:azure-specs
ResourceOperationStatus inherited its description through `is`, and LocationOfCreatedResourceResponse.location through its ResourceLocation type. The new doc comments were overriding both in the emitted swagger, so pin the API-facing text with @doc and keep the doc comment for the reference docs.
Timothee Guerin (timotheeguerin)
marked this pull request as ready for review
August 7, 2026 15:22
Timothee Guerin (timotheeguerin)
requested review from
iscai-msft,
Laurent Mazuel (lmazuel),
m-nash,
Mark Cowlishaw (markcowl) and
Jeff Fisher (xirzec)
as code owners
August 7, 2026 15:22
…imotheeguerin/library-linter-missing-docs
`@doc("")` set the header description to an empty string instead of letting it
inherit "The location of an instance of {name}" from ResourceLocation.
Mark Cowlishaw (markcowl)
left a comment
Mark Cowlishaw (markcowl)
left a comment
Member
There was a problem hiding this comment.
One nit. I think we should see the impact on the specs repo (if any) and correct in typespec-next before merging.
Mark Cowlishaw (markcowl)
approved these changes
Aug 7, 2026
Mark Cowlishaw (markcowl)
left a comment
Mark Cowlishaw (markcowl)
left a comment
Member
There was a problem hiding this comment.
Need to have a pr fixing typespec-next (and hopefully in the private repo as well)
Timothee Guerin (timotheeguerin)
deleted the
timotheeguerin/library-linter-missing-docs
branch
August 7, 2026 18:03
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
microsoft/typespec#11543 adds
missing-documentationandextraneous-documentationrules to@typespec/library-linter. Every Azure library already runs the linter with--warn-as-erroras part of itsbuildscript, so the moment that PR lands our builds break — 94 warnings across azure-core, ARM, TCGC and portal-core.This documents the gaps so the core PR can merge cleanly.
Two categories of problems turned up, and both were hiding real content from the published reference docs:
Doc comments starting with a tag swallowed the whole description.
@deprecatedisn't a tag the compiler knows, so everything after it became tag content and the description vanished:@operationGroupandResourceOperationsnow actually show their description on the website. Same story forAzure.Core.ResourceOperationStatus, whose only doc was behind a@devtag.@templatetags pointing at parameters that don't exist. Operations insideResourceOperations,PrivateLinksand friends documented their interface's template parameters, and a few models still referenced pre-rename names (@template TonLocationOfCreatedResourceResponse<Resource>). Those are now either corrected or removed.The rest is plain missing docs on properties, enum members, template parameters and decorator parameters.
Emitted output
Descriptions on ARM common types flow into the generated swagger, so
packages/samples/common-typespicks up a few additivedescriptionfields onNetworkSecurityPerimeterConfigurationProvisioningStateandSeverityenum values — consistent withIssueTypeandResourceAssociationAccessMode, which already carry them.Verified with
tsp compile . --warn-as-error --import @typespec/library-linteragainst the linter build from the core branch: all six libraries are clean, and the full test suites for the touched packages pass unchanged.