Comments (14)
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.)
from jsdoc.
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.
from jsdoc.
Yes.
from jsdoc.
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)?
from jsdoc.
I am interested @mathematicalcoffee .
from jsdoc.
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");
}
};
from jsdoc.
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?)
from jsdoc.
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.)
from jsdoc.
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.
from jsdoc.
Any updates on this? ahocevar's hack seems to do ok as a workaround, but i'm curious where things are with 3.3
from jsdoc.
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.
from jsdoc.
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.
from jsdoc.
For posterity: JSDoc 3.3.0-alpha13 fixes the crash.
from jsdoc.
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?
from jsdoc.
Related Issues (20)
- JSDoc does not correctly parse the default value of the property tag
- Does it work with unknown tags ? HOT 1
- Instance members starting with a hash are not documented correctly. HOT 1
- jsdoc.app page down HOT 1
- jsdoc fails when ES6 classes have private members (`#fieldname`)
- Mixin fields are documented twice on class declarations with a constructor HOT 1
- jsdoc for globalThis
- How to document properties with colon? HOT 2
- npmignore includes necessary `test` directory
- Filtering an output before generating documentation
- Tests fail on Node.js 20.10.0 (and maybe Node.js 20.x)
- Inline syntax HOT 9
- Description getting generated twice in the HTML HOT 1
- MetaMask
- Bug in nodeToValue conversion of object literals
- [Question] Documenting destructured function argument with rest parameter
- saltydb missing inner join used in default template HOT 4
- How do I read JSDocs?
- Bug: with option `-c` config file ends with `.cjs` is still treated as JSON
- BUG: Use object shorthand or index signatures being applied to JavaScript files
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from jsdoc.