rushstack
rushstack copied to clipboard
microsoft
[api-extractor] Don't annotate items with `{@inheritDoc}` comments as "undocumented" in API reports
For API members documented with {@inheritDoc Foo}, the resulting generated API report marks these as // undocumented. This isn't true, and leads to confusion in PRs, etc. It would be immensely helpful if the logic determining whether or not an API is documented checks for the {@inheritDoc} tag.
More generally, it seems like APIs whose documentation consists only of tags counts as undocumented (ex: a function with only an @returns foo or an {@inheritDoc}.
This seems wrong to me. If this is a desired behavior, or we want to change it without breaking existing users, offering a configuration option to select the other behavior (counting tags as documentation) could work.
Another approach (still possibly behind config) would be to change the comment in these cases from // (undocumented) to something more specific like // (tags only documentation). Personally, I don't think this is useful, but if people do want to know about items with who's documentation only contains tags this seems like a better way than just going with the existing // (undocumented).
Another case I just noticed, constructor parameter properties also show up as undocumented even when documented.
Policy appears to be implemented in https://github.com/microsoft/rushstack/blob/main/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts#L134
For API members documented with
{@inheritDoc Foo}, the resulting generated API report marks these as// undocumented. This isn't true, and leads to confusion in PRs, etc. It would be immensely helpful if the logic determining whether or not an API is documented checks for the{@inheritDoc}tag.
Could you give more specific repro steps?
For example, here is a definition with {@inheritDoc}:
https://github.com/microsoft/rushstack/blob/2e26d1f5d95118c6a96f45371fda8bc2d4d15a7f/build-tests/api-extractor-test-01/src/TypeReferencesInAedoc.ts#L18-L20
And here you can see that the result is NOT annotated as undocumented:
https://github.com/microsoft/rushstack/blob/2e26d1f5d95118c6a96f45371fda8bc2d4d15a7f/build-tests/api-extractor-test-01/etc/api-extractor-test-01.api.md?plain=1#L187-L189
To clarify, the meaning of // (undocumented) is not about whether you its type signature was supplemented with TSDoc technical tags. It is based on whether there is human documentation, a natural language explanation has been written to describe its purpose:
https://github.com/microsoft/rushstack/blob/d861d220962eff992278cb732ee5d4d3e4a97517/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts#L136-L144
The {@inheritDoc} tag can provide this documentation, but only if the referenced /** */ tag itself contains documentation.
Class constructors get special exemption because often there is not much to say about them. If you don't write anything, API Extractor will automatically document it with a message like Constructs a new instance of the X class.
@octogonz Sorry for the delay. The fluid-framework repo has a repro of this here: https://github.com/microsoft/FluidFramework/blob/main/packages/tools/devtools/devtools/api-report/devtools.api.md?plain=1#L36.
Source code for the item with the inheritDoc comment is here: https://github.com/microsoft/FluidFramework/blob/main/packages/tools/devtools/devtools/src/index.ts#L153
And the source code for the target item is here: https://github.com/microsoft/FluidFramework/blob/main/packages/tools/devtools/devtools-core/src/FluidDevtools.ts#L402
In this case, which I suspect is key, the inheritDoc target is in another package. So presumably API-Extractor can't validate if the target actually has non-release-tag contents, so we're assuming the item is undocumented? If this is the case, it seems like the policy should be to not report undocumented when it's ambiguous.