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 On Mon, Oct 24, 2022 at 9:48 AM Mark Banner <[email protected]> wrote: > 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 > <https://bugzilla.mozilla.org/show_bug.cgi?id=1510561> these across to > use rules from the supported eslint-plugin-jsdoc > <https://github.com/gajus/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 > > <https://searchfox.org/mozilla-central/source/tools/lint/eslint/eslint-plugin-mozilla/lib/configs/valid-jsdoc.js> > - For checking that comments are valid with the jsdocs specification > - require-jsdoc > > <https://searchfox.org/mozilla-central/source/tools/lint/eslint/eslint-plugin-mozilla/lib/configs/require-jsdoc.js> > - 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 > > -- > You received this message because you are subscribed to the Google Groups " > [email protected]" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > 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 > <https://groups.google.com/a/mozilla.org/d/msgid/dev-platform/1ef48a1f-f199-5009-e66f-9037fb28c4c9%40mozilla.com?utm_medium=email&utm_source=footer> > . > -- You received this message because you are subscribed to the Google Groups "[email protected]" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/a/mozilla.org/d/msgid/dev-platform/CA%2B3p4ua7LZLfY7LDqvw6isOgLb38Qy9D-pD4saPCr6SGw-W8ZA%40mail.gmail.com.
