docs: incorrect descriptions for inherited class members #22766
Conversation
crisbeto
added
P3
google-cla
bot
added
the
cla: yes
There was a problem hiding this comment.
I've looked more into this as it surprised me that the Dgeni TS package would process inherited classes differently. It looks like the docs miss the description field because we manually construct the ClassExportDoc for inherited classes, and these docs are not processed e.g. by the dgeni-packages/jsdoc processors, hence missing the various tag field and description.
I wonder if there is a better solution to this; this is definitely better than using content for now, but it's rather a workaround for a more general problem that could cause issues in other places (e.g. if we test for JSDoc tags elsewhere).
Could you update the comment with a TODO in merge-inherited-properties.ts?
|
I agree that it's a hacky solution and I'll add the TODO, but I'm not sure that the explanation is correct. I was testing against the classes that extend from |
In angular#22482 some changes were made that switched the doc rendering from `description` to `content` in an attempt to expose the descriptions for inherited class members. It turns out that `content` is actually the description of the member including `@param` and `@returns` tags which we don't want to show either. After some investigation, it turns out that the root cause of the descriptions not being shown is that dgeni won't assign a `description` if the base class isn't exported. These changes resolve the issue by falling back to `content` if there is no `description` and stripping out the JSDoc tags from it manually.
|
@crisbeto If To solve this, we have a custom processor that visits e.g. |
In #22482 some changes were made that switched the doc rendering from `description` to `content` in an attempt to expose the descriptions for inherited class members. It turns out that `content` is actually the description of the member including `@param` and `@returns` tags which we don't want to show either. After some investigation, it turns out that the root cause of the descriptions not being shown is that dgeni won't assign a `description` if the base class isn't exported. These changes resolve the issue by falling back to `content` if there is no `description` and stripping out the JSDoc tags from it manually. (cherry picked from commit 897e739)
|
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. |
In #22482 some changes were made that switched the doc rendering from
descriptiontocontentin an attempt to expose the descriptions for inherited class members. It turns out thatcontentis actually the description of the member including@paramand@returnstags which we don't want to show either.After some investigation, it turns out that the root cause of the descriptions not being shown is that dgeni won't assign a
descriptionif the base class isn't exported.These changes resolve the issue by falling back to
contentif there is nodescriptionand stripping out the JSDoc tags from it manually.