chore: filter alias exports in docs #8782
Conversation
Let's consider this example:
export {ObserveContent} from './X';
/** @deprecated */
export {ObserveContent as CdkObserveContent} from './X';
This is a common pattern inside of Angular Material, but causes Dgeni to generate documents for both exports.
The second document is identical to the original Dgeni document and doesn't even show the aliased name. It would be useful to have a property that indicates that the given doc is an alias and maybe also refer to the original document.
This commit introduces a processor that removes the duplicate documents from the docs.
Fixes angular#8693
googlebot
added
the
cla: yes
|
|
||
| // Remove the current export document if there are multiple Dgeni export documents with the | ||
| // same document id. If there are multiple docs with the same id, we can assume that this doc | ||
| // is an alias export. |
There was a problem hiding this comment.
Is there any way to more specifically target things marked as @deprecated? It's possible we may want to re-export something not as a deprecation, but as an alternate name (e.g. re-exporting something from cdk with "mat").
There was a problem hiding this comment.
I see. Unfortunately it's not possible to detect if the re-export was marked as deprecated.
/** @deprecated */
export {XX as PP} from './test';Dgeni doesn't provide access to the export statement/symbol. In theory it would be possible to walk through imports file by file using the AST, but this more turns into it's own docs generation tool then.
I assume even Dgeni in general (with angular/dgeni-packages#248) won't be able to differentiate between deprecated re-exports or normal re-exports.
There was a problem hiding this comment.
What if we formatted it like this?
export {XX as /** @deprecated */ PP} from './test';There was a problem hiding this comment.
Just tried that, but that information is being lost as well.
jelbourn
added
pr: lgtm
action: merge
|
This issue has been automatically locked due to inactivity. Read more about our automatic conversation locking policy. This action has been performed automatically by a bot. |
Let's consider this example:
This is a common pattern inside of Angular Material, but causes Dgeni to generate documents for both exports.
The second document is identical to the original Dgeni document and doesn't even show the aliased name. It would be useful to have a property that indicates that the given doc is an alias and maybe also refer to the original document.
This commit introduces a processor that removes the duplicate documents from the docs.
Related: angular/dgeni-packages#248 (already chatted with Pete about it).
Fixes #8693