Changing the way jsdoc is linted via ESLint

[Mark Banner]

Over the tree we have a few places where we use a couple of legacy ESLint rules for ensuring the correct formatting of jsdoc comments. We are now part way through transitioning the existing areas these across to use rules from the supported eslint-plugin-jsdoc plugin.

I wanted to highlight a couple of items coming out of this transition:

• We want our jsdoc configuration to be consistent across the mozilla-central tree. Therefore we have created two initial configurations (these might get merged later, but for roll-out it is easier to have them separate):
• valid-jsdoc - For checking that comments are valid with the jsdocs specification
  
• require-jsdoc - For checking that various items of the jsdoc are included when they should be
• The new configurations are slightly stricter that the older rules, however, this should lead to comments that better matching jsdoc's spec.

Initially we are focussing on transitioning the existing areas away from the legacy rules. Once that is complete, we'll think about how to roll this out to new areas - if anyone is interested in enabling this for their component, please let me know off-list or via #lint:mozilla.org on Matrix.

Finally, a shout out to trickypr who has been doing all the work on this transition.

Mark

[Mike Conley]

Hi Mark,

This is great! Really happy that we're going to start to converge on some consistent JSDoc styling - I, myself, am probably guilty of introducing my own conventions in a few places, and it'll be great to have something authoritatively consumable by JSDoc!

That having been said, along with getting us into a consistent state, is part of this project also to beef up the amount of automatically JSDoc-generated documentation that gets put up on Firefox Source Docs? The list of things that actually do that is quite small: https://searchfox.org/mozilla-central/rev/88f285c5163f73abd209d4f73cfa476660351982/docs/conf.py#52-67 - so is the plan to enable this consistent styling and then to add to this Python list, or is that more of a separate task that we leave up to the relevant owners / peers of the code?

-Mike

--
You received this message because you are subscribed to the Google Groups "dev-pl...@mozilla.org" group.
To unsubscribe from this group and stop receiving emails from it, send an email to dev-platform...@mozilla.org.
To view this discussion on the web visit https://groups.google.com/a/mozilla.org/d/msgid/dev-platform/1ef48a1f-f199-5009-e66f-9037fb28c4c9%40mozilla.com.

[Mark Banner]

On 24/10/2022 15:07, Mike Conley wrote:
> That having been said, along with getting us into a consistent state,
> is part of this project also to beef up the amount of automatically
> JSDoc-generated documentation that gets put up on Firefox Source Docs?
> The list of things that actually do that is quite small:
> https://searchfox.org/mozilla-central/rev/88f285c5163f73abd209d4f73cfa476660351982/docs/conf.py#52-67
> - so is the plan to enable this consistent styling and then to add to
> this Python list, or is that more of a separate task that we leave up
> to the relevant owners / peers of the code?

There's not been any discussion between the two areas.

On the ESLint side this is something we've wanted to do for a while -
the old rules are still supported, but they are legacy so they could get
dropped at some stage.

However, having docs that are more spec compliant will likely help the
automatic jsdoc generation, so it might be a good idea to link enabling
these together in some way.

Additionally, those existing jsdoc generated areas might be a good
starting point to roll the configurations out to more places - that way
developers can have local checks run before they push patches to automation.

Mark