Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

valid-jsdoc with inheritDoc #4576

Closed
thealjey opened this Issue Nov 30, 2015 · 15 comments

Comments

Projects
None yet
7 participants
@thealjey
Copy link

commented Nov 30, 2015

Currently the following comment block is violating the valid-jsdoc rule.

/**
 * @inheritDoc
 */

Regardless of whether the method is documented in the parent class or not.
Is this a bug, a feature or something that will be changed in the future versions?
Can I use @inheritDoc with this rule right now?

@eslintbot

This comment has been minimized.

Copy link

commented Nov 30, 2015

@thealjey Thanks for the issue! If you're reporting a bug, please be sure to include:

  1. The version of ESLint you are using (run eslint -v)
  2. What you did (the source code and ESLint configuration)
  3. The actual ESLint output complete with numbers
  4. What you expected to happen instead

Requesting a new rule? Please see Proposing a New Rule for instructions.

@eslintbot eslintbot added the triage label Nov 30, 2015

@gyandeeps

This comment has been minimized.

Copy link
Member

commented Nov 30, 2015

I dont understand the issue here, can you please answer all the questions (above post)?

@thealjey

This comment has been minimized.

Copy link
Author

commented Nov 30, 2015

Sorry, but it just seems like too much work for such a minor thing 😺
I simply removed the @inheritDoc and copied the whole comment block from the parent class.
I'll let whoever this bothers more than it does me to worry about this)))

@platinumazure

This comment has been minimized.

Copy link
Member

commented Nov 30, 2015

It's still not clear what happened, what you're expecting (and why you're
expecting it) vs what actually happened. Version information is also
helpful in case you're on an old version and this is fixable with an
upgrade. Please answer the questions above.
On Nov 30, 2015 9:08 AM, "Eugene Kuzmenko" notifications@github.com wrote:

Sorry, but it just seems like too much work for such a minor thing [image:
😺]
I simply removed the @inheritdoc and copied the whole comment block from
the parent class.
I'll let whoever this bothers more than it does me to worry about this)))


Reply to this email directly or view it on GitHub
#4576 (comment).

@thealjey

This comment has been minimized.

Copy link
Author

commented Nov 30, 2015

JSDoc 3.4.0
The rest is pretty much described in my original post (there's a documented method in a parent class and the same method in a child class with /** @inheritDoc */, that's it).
Sorry, but this is as much as I can bring myself to write right now.

@nzakas

This comment has been minimized.

Copy link
Member

commented Nov 30, 2015

@thealjey We really need a clear example to work with to be able to both evaluate and potentially fix any bug. Keep in mind we get dozens of issues filed over the course of a week, so the more information you can provide, the more likely it is that someone will investigate further.

@cschuller

This comment has been minimized.

Copy link
Contributor

commented Dec 18, 2015

@thealjey Specification by code example is a great way to explain things:

What @thealjey meant was something like this:

'use strict';

/**
 * @constructor
 */
function Foo() {
    /**
     * @param {string} baz The first argument.
     * @return {void}
     */
    this.bar = function bar(baz) {};
}

/**
 * @constructor
 * @inherit {Foo}
 */
function MeAlsoFoo() {
    /**
     * @inheritDoc
     */
    this.bar = function bar(baz) {};
}

with a default valid-jsdoc config. will result in

  19:5  error  Missing JSDoc @returns for function  valid-jsdoc
  19:5  error  Missing JSDoc for parameter 'baz'    valid-jsdoc

I guess there is just no support for @inheritDoc within the valid-jsdoc rule. The implementation will not be easy, because currently the valid-jsdoc rule does not parse / know anything about types like {string} or {Foo} used within @inherit

This is more a new feature of the rule itself than a bug.

@nzakas

This comment has been minimized.

Copy link
Member

commented Dec 19, 2015

So in this case, we would just not check any JSDoc with inheritDoc?

@cschuller

This comment has been minimized.

Copy link
Contributor

commented Dec 19, 2015

Yes, not checking sounds good.

Let's go for it, because there is already an "not-check" implementation for @override (#3629).

We can add an additional option noInheritDoc to disallow using of @inheritDoc. If so then we also need to add another option noOverride to be consistent with current implementation.

I can do the implementation within the next 14 days (issue doesn't seem to be very critical).

@nzakas

This comment has been minimized.

Copy link
Member

commented Dec 19, 2015

I don't think we need an option (since we don't have one for override either). It can just be the default behavior.

@cschuller

This comment has been minimized.

Copy link
Contributor

commented Dec 19, 2015

Okay. I'm going to do this, give me two weeks. ;-)

@nzakas

This comment has been minimized.

Copy link
Member

commented Dec 21, 2015

Awesome, thanks @cschuller

@alberto

This comment has been minimized.

Copy link
Member

commented Dec 23, 2015

I think there is already support for this: https://github.com/eslint/eslint/blob/master/lib/rules/valid-jsdoc.js#L165

The correct syntax is inheritdoc (with lowercase d) http://usejsdoc.org/tags-inheritdoc.html

@nzakas

This comment has been minimized.

Copy link
Member

commented Dec 23, 2015

Ah, I'm pretty sure that JSDoc is case insensitive when it comes to tags, so we probably just need to normalize the tag name to lowercase before that point.

@cschuller

This comment has been minimized.

Copy link
Contributor

commented Dec 23, 2015

  • The JSDoc documentation is using lowercase @inheritdoc JSDoc
  • The Google Closure Compiler expect a camelcase @inheritDoc Google Developers
  • WebStorm 11 likes to have a camelcase @inheritDoc

I think a tag name normalization will do it. camel/lower case is then more a matter of styling.

@alberto alberto closed this in 9ea6b36 Dec 24, 2015

gyandeeps added a commit that referenced this issue Dec 24, 2015

Merge pull request #4796 from eslint/issue4576
Update: Ignore case in jsdoc tags (fixes #4576)

@eslint eslint bot locked and limited conversation to collaborators Feb 7, 2018

@eslint eslint bot added the archived due to age label Feb 7, 2018

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
You can’t perform that action at this time.