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

linter.verify() `config` param under- / mis-documented #5104

Closed
jmm opened this issue Jan 30, 2016 · 17 comments

Comments

Projects
None yet
4 participants
@jmm
Copy link
Contributor

commented Jan 30, 2016

The linter.verify() docs provide no explanation of what config consists of, and the source code docs are incorrect:

@param {Object} config An object whose keys specify the rules to use.

Please consider:

  • Updating the source code docs for 1.x and 2.x to be accurate.
  • Updating the end user docs to explain what it consists of. I'm guessing it's a subset of the CLIEngine opts. I haven't checked, but I assume the verify() docs really mean it when they say "It doesn't do any filesystem operations" (and a later example on the page supports that), meaning that options like configFile|useEslintrc wouldn't be applicable.

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

@eslintbot

This comment has been minimized.

Copy link

commented Jan 30, 2016

@jmm 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.

@ilyavolodin

This comment has been minimized.

Copy link
Member

commented Jan 30, 2016

Thanks for noticing @jmm

@BYK BYK self-assigned this Feb 7, 2016

@BYK

This comment has been minimized.

Copy link
Member

commented Feb 7, 2016

Working on this.

BYK added a commit that referenced this issue Feb 7, 2016

BYK added a commit that referenced this issue Feb 7, 2016

@jmm

This comment has been minimized.

Copy link
Contributor Author

commented Feb 8, 2016

Thanks all!

It's great that you updated the source code docs with the ESLintConfig part. This still isn't a great description:

An object whose keys specify the rules to use.

@BYK

This comment has been minimized.

Copy link
Member

commented Feb 8, 2016

@jmm - Anything you have in mind to make it better/more descriptive?

@jmm

This comment has been minimized.

Copy link
Contributor Author

commented Feb 8, 2016

@BYK Is the in-source documentation used to generate anything else? If not, maybe just replace that description with something like "See the ESLintConfig type definition.", since it's right there above it. Or even just "See above"?

@BYK

This comment has been minimized.

Copy link
Member

commented Feb 13, 2016

@jmm - Sure, I'd give that a shot. Thanks for the suggestion!

@BYK

This comment has been minimized.

Copy link
Member

commented Feb 13, 2016

@jmm - Welp, looking at the code again. I think that would be a redundant comment since the type info is also associated with that line. Taking no action for the time being.

@jmm

This comment has been minimized.

Copy link
Contributor Author

commented Feb 15, 2016

@BYK Just delete this then (because it's wrong)?:

An object whose keys specify the rules to use.

@BYK

This comment has been minimized.

Copy link
Member

commented Feb 15, 2016

@jmm - Why do you think it is wrong?

@BYK

This comment has been minimized.

Copy link
Member

commented Feb 15, 2016

Shall we say "A key-value mapping for the rules where keys are rule names and values are the rules' configuration"?

@jmm

This comment has been minimized.

Copy link
Contributor Author

commented Feb 15, 2016

@BYK I'm not sure how we have a disconnect on this, since you partially fixed it like this:

// Before 
@param {Object} config

/// after
@param {ESLintConfig}

It is an ESLintConfig object, not a hash of rule name => rule config. The rules are in config.rules. No?

(BTW, what format exactly are you using for the docs in the source [@param, etc.]?)

@BYK

This comment has been minimized.

Copy link
Member

commented Feb 15, 2016

@jmm - you're right, sorry. Context switching :) Submitted #5288.

@BYK

This comment has been minimized.

Copy link
Member

commented Feb 15, 2016

(BTW, what format exactly are you using for the docs in the source [@param, etc.]?)

No sure I understand this question. Can you clarify?

@jmm

This comment has been minimized.

Copy link
Contributor Author

commented Feb 15, 2016

@BYK

@jmm - you're right, sorry. Context switching :)

No problem. Ah yes, that age old culprit.

Submitted #5288.

Thanks!

No sure I understand this question. Can you clarify?

Sure. I mean is it JSDoc, Doxygen, ...? In particular, is @param for sure the right thing here? Should it not be @property or something?

@BYK

This comment has been minimized.

Copy link
Member

commented Feb 15, 2016

@jmm yup, they should have been @property tags, good catch! Let me update #5288 accordingly.

BYK added a commit that referenced this issue Feb 15, 2016

@jmm

This comment has been minimized.

Copy link
Contributor Author

commented Feb 15, 2016

@BYK Thanks!

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

@eslint eslint bot added the archived due to age label Feb 6, 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.