Add TomDoc support to no-deprecated rule

[josh]

Closes #302.

[josh]

Re: #302 (comment)

@benmosher what do you think? Does it feel too ad-hoc to have a mini tomdoc parser as part of this repo?

[benmosher]

Looks good, in theory. I am a little concerned about spurious flagging, though. I think I'd like to have a "style" parameter that defaults to JSDoc but can allow specification of TomDoc.

[josh]

Ah, sorry. I forgot you mentioned that in the other thread. Yeah, I'll make
this modal.
On Mon, May 9, 2016 at 2:49 AM Ben Mosher notifications@github.com wrote:

Looks good, in theory. I am a little concerned about spurious flagging,
though. I think I'd like to have a "style" parameter that defaults to JSDoc
but can allow specification of TomDoc.

—
You are receiving this because you authored the thread.
Reply to this email directly or view it on GitHub
#321 (comment)

[benmosher]

It probably needs to be a setting, at least for now, though (not a rule parameter--I misspoke above).

Parsing of imported modules can occur during evaluation of any rule, and only happens once, so the option would have to be exposed on context.settings for the ExportMap parse to know about it reliably.

Something like import/docstyle maybe? Actually, I summon @jfmengels to think of a better setting name? 😅 I'm not sure what to call the class of things that JSDoc/ESDoc/TomDoc specify. doctype? docstring-type?

Default value should probably be documented as jsdoc, though I think it matches ESDoc.

[jfmengels]

I summon @jfmengels to think of a better setting name

I always delegate that part to others myself :p, but I like docstyle ;)

I think it would be nice if this setting accepted an array of strings, like XX: ["tomdoc", "jsdoc"], in case you have multiple doc styles in your repo (while transitionning?), or simply no style (sometimes it's this, sometimes it's that...).

[josh]

Is there a better place to define plugin default settings so it gets merged correctly with any user config?

[benmosher]

Not at the moment, nope. I've been doing it as-hoc as you've done here.

[josh]

@benmosher what do you think so far? The integration still feels a little gross, but I don't think I understand enough of the requirements for building a useful abstraction that will allow other doc parsers to hook in.

[benmosher]

I think it looks good.

I'm a little torn on specifying parsers as an object vs. just a list of strings. I can't think of any reason one would explicitly disable one (i.e. {jsdoc:false} is meaningless vs. just omitting) but it does allow potentially passing an object of options, later down the road (if it comes to that).

So I think it's probably good as-is, to start. Doesn't feel like it's worth publishing the contents of captureTomDoc to npm just to say that you can specify any arbitrary docparser.

So, yeah, a good first step towards general support for alternate metadata formats. 😄

[jfmengels]

I agree with @benmosher, I'd also prefer a list of strings, would make the settings a bit shorter and more readable in the config.

[josh]

I'm a little torn on specifying parsers as an object vs. just a list of strings.

👍 I'll make that change

[josh]

Sorry, I think I forgot to comment that I updated the PR with @jfmengels "list of strings" suggestion.

[benmosher]

Ah, sweet. LGTM

[benmosher]

Actually can you document this new functionality in the rule's documentation and add a blurb to the change log?

[josh]

Actually can you document this new functionality in the rule's documentation and add a blurb to the change log?

Done.

[benmosher]

Can you document the import/docstyle setting as well? Probably just in the rule documentation for now, since nothing else references it.

See the main README for examples of existing setting documentation. I normally like to include a snippet of example .eslintrc config (in YAML). You don't need to follow suit, just offering as a reference.

Getting close. Sorry this has been dragging, I've been busy IRL. 😅

[josh]

Can you document the import/docstyle setting as well? Probably just in the rule documentation for now, since nothing else references it.

Good call! I actually forgot it was opt in for a second.

Getting close. Sorry this has been dragging, I've been busy IRL. 😅

No worries! 😄 You've been giving great feedback.

[josh]

Thanks!