1857349 - Support custom element JSDoc tags

Status: NEW

(Developer Infrastructure :: Lint and Formatting, task, P3)

Description

[Mark Striemer [:mstriemer]]

When documenting custom elements it's helpful to be able to define the @tagname and any @slots that it creates, among some other tags. These aren't included in JSDoc 3 but are used by custom-elements-manifest to generate documentation from JSDoc (supported JSDoc tags.

Some tags we should likely support:

• @attribute, @attr
• @csspart, @part
• @cssproperty, @cssprop
• @slot
• @tagname, @tag

If we only want to support a single version of these I'd opt for the long form, which are all first in each bullet of that list.

It looks like we should be able to update the config for valid-jsdoc.js to include something like:

module.exports = {
  plugins: ["jsdoc"],
  rules: {...},
  settings: {
    jsdoc: {
      definedTags: ["attribute", "csspart", "cssproperty", "slot", "tagname"],
    },
  },
};

Comment 1

[Mark Banner (:standard8)]

I don't see an issue with supporting more tags. I do think it would be better to support just one form, so that we have consistency over the code base, and the longer form seem better for that.

Comment 2

[Dave Townsend [:mossop]]

(In reply to Mark Banner (:standard8) from comment #1)

I don't see an issue with supporting more tags. I do think it would be better to support just one form, so that we have consistency over the code base, and the longer form seem better for that.

No issue here. I have a slight preference towards the shorter forms as they seem clear enough and quicker to type and take up less room in our restricted line length but I'm happy with either so long as we standardise.