compiler api: jsdoc parse optional params

[atanasster]

Suggestion

Optional jsdoc parameters are currently lost on @param: https://jsdoc.app/tags-param.html

🔍 Search Terms

jsdoc optional params

⭐ Suggestion

Please allow for optional params parsing

  /**
  * @param {string} [somebody] - Somebody's name.
  */
  export function sayHello(somebody) {
  }

currently parses to tags:

   {
      name: "param",
      text: [
        {
          text: "somebody",
          kind: "parameterName",
        },
        {
          text: " ",
          kind: "space",
        },
        {
          text: "- Somebody's name.",
          kind: "text",
        },
      ],
    },

Possible suggestions:

• add a node kind: optional,
• or keep the square brackets around the name so users have a way to parse the optional parameter name:

 {
    text: "[somebody]",
    kind: "parameterName",
  },

📃 Motivating Example

example test to reproduce https://github.com/atanasster/ts-issues/blob/master/tests/optional-param.test.ts

[sandersn]

The services part of the Typescript API is not intended for semantic analysis, but for display. Parameter optionality is displayed on signature help, not on the parameter tag.

I'd recommend using the compiler part of the Typescript API, like so:

// existing code ..
const symbol = exports[0]
const params = ts.getALLJSDocTagsOfKind(
  symbol.valueDeclaration, 
  ts.SyntaxKind.JSDocParameterTag
) as ts.JSDocParameterTag[]
for (const p of params) {
  p.isBracketed
  // inspect other properties of the tag here...
}

The compiler API exposes the parse tree and is intended to answer syntactic and semantic questions. It's more appropriate if you're not building an editor.

[atanasster]

thank you very much, the compiler API it seems much more appropriate for what I am building. Will try to switch and will close all my jsdoc-related suggestions.
Any pointers for docs on the jsdoc compiler API?

[sandersn]

Our documentation isn't very good, but the API isn't too complicated? The main wrinkle is that, say, getJSDocTags takes a node that you're interested in and the API provides you with all related tags, even those that aren't directly attached to that node.