Support for @inheritDoc as an inline tag

[Ayfri]

Search terms

inherited

Expected Behavior

Getting the got inherited.

Actual Behavior

When putting this code :

interface EventsOptions {
	/**
	 * The name of the event.
	 */
	readonly name: string;
}

export class Event implements EventsOptions {
	/**
	 * {@inheritDoc EventsOptions.name}
	 */
	public readonly name: string;
}

Getting literal {@inheritDoc EventsOptions.name} for name property.

Environment

• Typedoc version: 0.20.16
• TypeScript version: 4.1.3
• Node.js version: 15.6.0
• OS: Windows 10 20H2

[Gerrit0]

TypeDoc doesn't support @inheritDoc as an inline tag yet - remove the surrounding braces.

[Gerrit0]

You'll also need to upgrade to 0.20.17 to get the redirected name behavior.

[Ayfri]

I've upgraded and changed the syntax but now Prettier removes EventOptions.name after the tag, every time, whatever I do...

[Gerrit0]

Prettier doesn't do that to me... Do you have some plugin installed that adds TSDoc support? If so, you might have to turn that off to use TypeDoc - it doesn't fully support TSDoc yet.

[Ayfri]

I have eslint & eslint-plugin-tsdoc, does it can be that?

[Gerrit0]

eslint-plugin-tsdoc might be doing it - I don't use it, so not sure...

[Dergash]

I've tested your code sample on my project configured with esling-plugin-tsdoc and prettier and received only a warning:

243:8   warning  tsdoc-tag-should-not-have-braces: The TSDoc tag "@inheritDoc" is not an inline tag; it must not be enclosed in "{ }" braces 

Parameter was not deleted by linter. If you have an example project I can take a look why it was removed in your case.

Concerning the warning, I believe there is an open issue in eslint-plugin-tsdoc to allow more flexible configuration for plugin rules.

[Ayfri]

Here.

The code snippet is from the Event class.

[Dergash]

Thanks for the repro.

I believe it is removed due to jsdoc/empty-tags rule which is enabled from

"extends": [
    "plugin:jsdoc/recommended"
],

configuration in your package.json
If you disable this particular rule:

"rules": {
    "require-jsdoc": "warn",
    "jsdoc/check-tag-names": "off",
    "jsdoc/require-param-type": "off",
    "jsdoc/require-returns-type": "off",
    "jsdoc/empty-tags": "off" // this
}

it will no longer be removed.

It seems your project uses both jsdoc and tsdoc validation for ts files. Personally I'd configure to check TSDoc on .ts files and JSDoc on .js files.

[Ayfri]

I added JSDoc checking to ensure that JSDoc is put on every function/class/method, and I do not have any JS files (apart from the automatically-generated documentation).

[Dergash]

Considering eslint-plugin-tsdoc does not currently have equivalent for require-jsdoc it seems acceptable to use both in this case, but probably only enable one specific rule from it (require-jsdoc) and leave other checks for eslint-plugin-tsdoc.

Anyway, it's not a big deal and you should be fine with just disabling jsdoc/empty-tags rule in your package.json.

Other possible resolutions for your issue are either:

1. Wait for support for inline @inheritDoc in Typedoc
   or
2. Wait for support for configurable .tsdoc in eslint-plugin-tsdoc

P.S. Have to take note on misleading message from eslint-plugin-tsdoc; while being an inline tag in their internal tag classification and being used without braces, it is reported by plugin as not inline tag which should not have bracers, although there weren't any. Weird.

[Ayfri]

Okay okay, thanks for all this information, I think that I'm gonna wait for option 1 and keep the code like how it is for now.
By the way, why does Typedoc doesn't handle @inheritDoc the same way as TSDoc?

[Dergash]

My understanding is that Typedoc have been around for 7 years while TSDoc only for 3 years and a lot of things inside TSDoc are ongoing process, so there was no standard for @inheritDoc back then and it'll take some time to catch up with them now.

[Ayfri]

Okay, I see, thanks.
Close the issue if when needed and goodbye!

[Gerrit0]

Support added in 0.23: https://typedoc.org/tags/inheritDoc/

[takthetank]

Hi, I'm on latest version 0.23.23 and it seems that my comments don't work for properties inhertied from an interface.
See the following sample to reproduce:

export abstract class FooClass {
   /** Describes what this method does */
   public fooMethod(): void{
      // do stuff
   }
}

export interface BarInterface {
   /** Describes the property */
   barProp: string;
}

export class FooBarClass extends FooClass implements BarInterface{
   /** {@inheritdoc BarInterface.barProp} */
   public barProp: string=''; /** comments not inherited */

   /** {@inheritdoc FooClass.fooMethod} */
   public fooMethod(): void { /** comments inherited fine */
      // do something first
      super.fooMethod();
   }
}

[Gerrit0]

Please open a new issue with bug reports rather than posting in old closed issues

[takthetank]

Sorry, that seemed the same issue to me, I'll post a new one.