RFC: Inheriting documentation comments

[Gerrit0]

Though not documented on the website (oops!), TypeDoc has some rudimentary support for inheriting documentation via the @inheritDoc tag.

In 0.22, there are two forms that this tag can take:

/** @inheritDoc */
/** @inheritDoc someSymbol.reference.here */

With the first, TypeDoc will look up the property/method from a parent class and copy in the comment.
With the second, TypeDoc will use the symbol reference to grab the comment and use that instead. It also tries to be closer to the TSDoc specification, where only parts of the comment are copied (but I think still doesn't exactly match)

There are a few problems:

1. With the second form, TypeDoc doesn't check to ensure that the comment we are inheriting from has been "resolved", so the inherited documentation might include @inheritDoc, which won't be resolved.
2. Neither of these forms are valid according to TSDoc, which expects {@inheritDoc declarationReference}
3. Neither of these forms, nor TSDoc's form, allows extending a summary with documentation from another member (use case in #304)

My goals, in making implementation decisions:

1. TypeDoc shall not force users to write comments which results in a degraded editor experience (VSCode) (dropping support for the form without a reference is out of consideration)
2. TypeDoc's implementation should provide intuitive results that match what users expect from quick infos (today, this only affects the @inheritDoc with no reference form)
3. TypeDoc's implementation should be "best effort", supporting as many existing patterns as possible.
4. TypeDoc should permit TSDoc compatible syntax, if it does not negatively affect a previous goal.

Here's what I'm thinking how TypeDoc should work... thoughts?:

/** @inheritDoc */ - Duplicate TypeScript's behavior of looking at base classes then implemented interfaces. (What shows up in tooltips)
/** {@inheritDoc a.b.c} */ - Follow TSDoc, particularly the implementation of api-extractor since the documentation page is not sufficiently precise.
/** @inheritDoc a.b.c */ - Deprecate? Leave in place, but make it follow TS's behavior of merging comments?

See also:

• Support @copydoc or enhance @inheritdoc #304
• Support for @inheritDoc as an inline tag #1480
• Use documentation comments from inherited properties when @inheritDoc is present microsoft/TypeScript#18804
• https://jsdoc.app/tags-inheritdoc.html
• https://tsdoc.org/pages/tags/inheritdoc/

CC: @Dergash @RunDevelopment @Ayfri

[RunDevelopment]

Thanks for tagging me @Gerrit0!

Firstly, I mostly agree with the goals and your suggested solution. Doing what everybody else is doing already instead of creating a TypeDoc-specific @inheritDoc tag is the right move IMO.

I disagree with is the "as many existing patterns as possible" part in goal 3. Supporting both TSDoc's and TypeScript's will be difficult enough as is. We got quite lucky that there is no syntactic overlap so we can actually differentiate TSDoc @inheritDoc tags from TS @inheritDoc tags. We might not get so lucky with a thrid pattern.

---

As a user, I would intuitively expect that /** @inheritDoc */ is the same as /** @inheritDoc ref */ with TSDoc just picking the reference for me. That being said, I would only expect this behavior if /** @inheritDoc ref */ was an option.

Deprecating it seems like the best option since /** @inheritDoc ref */ and /** {@inheritDoc ref} */ almost do the same thing. This would also remove the last remaining TypeDoc-specific @inheritDoc tag.

Silently changing changing the behavior of /** @inheritDoc ref */ in the next major (0.x) release would mean people would have update their code to the more silimarly behaving /** {@inheritDoc ref} */ anyway. Why keep /** @inheritDoc ref */ then?

---

The difference between TSDoc and TypeScript @inheritDoc tags is interesting. The differences have to clearly communicated to the user. Otherwise, this will cause confusion.

TypeDoc should probably issue warnings if it detects invalid @inheritDoc tags (e.g. a non-inline tag with a reference (or any text really), an inline tag with no/invalid reference).