@inheritDoc and @override tags support.

[gituliar]

Currently JSDoc ignores @inheritDoc and @override tags, however it would be nice to replace them with superclass's (modified in case of @overrride tag) docstrings in HTML documentation.

[leeight]

Yes.

[mathematicalcoffee]

I have a plugin that sort of does this (well it has an @inheritparams <othersymbol> to inherit just params and returns, @inheritdoc <othersymbol> to inherit params, returns, classdesc, summary, function description etc, and @override which is the same as @inheritdoc but guesses the symbol to inherit from (as being the parent's method of the same name).

I can share if you interested (it works for my code but is not widely tested)?

[tregusti]

I am interested @mathematicalcoffee .

[ahocevar]

Having this fixed would be a great for http://github.com/openlayers/ol3 as well. For now I have created a custom plugin that replaces @inheritDoc annotations with an empty comment with 3 asterisks:

/***
 *
 */

The strange but useful side effect of this is that the inherited docs get applied then. This is the plugin code:

exports.handlers = {
  beforeParse: function(e) {
    e.source = e.source.replace(
        /\/\*\*\r?\n?\s*\* @(inheritDoc|override)\r?\n?\s*\*\/\r?\n?/g,
        "/***\n *\n */\n");
  }
};

[hegemonic]

As noted on the mailing list, I'm currently planning to implement this for JSDoc 3.3.

It would also be useful to support something like the JSDuck flavor of this tag (à la @mathematicalcoffee's plugin), which allows you to specify where to inherit from:

/** @class */
function MyClass() {}

/**
 * A great method with a very wordy description that I want to reuse
 * somewhere else because I don't like typing and I try to keep things DRY
 * and I don't feel like writing more docs and it's late and I'm tired.
 */
MyClass.prototype.foo = function() {};

/**
 * @inheritdoc MyClass#foo
 */
MyClass.prototype.bar = function() {};

I also think that any tags in MyClass#bar (including a description) should override the corresponding tags from MyClass#foo. That handles the case where you want to inherit the docs for the parameters, but not the method description. (Although I guess that could get tricky for repeatable tags: What happens if the original method has docs for the foo, bar, and baz parameters, and the method with @inheritdocs only has docs for the foo parameter? How tricky would it be to merge those two doclets?)

[hegemonic]

Also, if a subclass overrides a superclass' method, and the subclass' method doesn't have any docs, let's assume the user meant to put an @inheritDoc tag on the subclass' method. (If the superclass' method is abstract, we should also replace the @abstract tag with the new @implements <method> tag.)

(Updated 2013-06-11 to address abstract methods.)

[mathematicalcoffee]

The plugin I wrote (out of date, written 5 months ago and not updated to new parseComplete events) would just put 'undocumented' in the case of the original method having and documenting foo but the inheriting method having foo, bar and baz with the latter two undocumented.

[abelnation]

Any updates on this? ahocevar's hack seems to do ok as a workaround, but i'm curious where things are with 3.3

[piotr-cz]

A workaround could be omitting docblock on the super method;
However this isn't working when parent is defined using function declaration and wrapped in IIFE (parent methods don't show up).

And it feels strange in code.

[hegemonic]

The @inheritdoc and @override tags are (finally!) implemented on master. Later this morning, I'll publish a new alpha version to npm that includes these tags.

If a symbol has the @inheritdoc or @override tag, the symbol will inherit docs from its parent class. All other docs for the symbol will be ignored.

You can use @inheritDoc as a synonym for @inheritdoc. Either will work.

We don't currently support explicit inheritance from a specific symbol (for example, @inheritdoc Foo#bar), simply because that will take more work. I'll file a new issue to add that feature in a future release.

[hegemonic]

The changes for this issue caused a weird crash to occur when generating docs for JSDoc itself. The fix is in 2b6d2de. The logic was clearly wrong, but it's not clear exactly what triggers the crash.

JSDoc 3.3.0-alpha12 includes support for the new tags. If others run into the same crash, I'll release a new alpha with the fix.

[hegemonic]

For posterity: JSDoc 3.3.0-alpha13 fixes the crash.

[chharvey]

What is the difference between @inheritdoc and @override? I tried swapping one out for the other in my code but I do not see a change in output.

In both cases, it simply repeats the documentation of the inherited member. (I cannot modify, say, a @param tag.)

[ackvf]

Anyone knows how to make this work in VSCode? I suppose they need to implement support for this tag themselves to display it in the IDE, right?