JSDoc param tag's default value parsing should support non-TS expressions

[atanasster]

Suggestion

probably related to #44930 but a different use case. default values on @param: https://jsdoc.app/tags-param.html

🔍 Search Terms

jsdoc param default value

⭐ Suggestion

Please allow for default value params parsing

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

currently parses to tags:

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

possibly add a new node

{
    text: "John Doe",
    kind: "defaultValue"
  },

and clean up the description from

{
  text: "Doe] - Somebody's name.",
  kind: "text"
}

to

{
  text: "- Somebody's name.",
  kind: "text"
}

p.s. it mighy also be worth in general to clean up parameter descriptions text from the leading hyphen

[atanasster]

Hi @sandersn , started converting to use the jsdoc compiler API and it worked great for isBracketed, thanks again.

However the default value issue above is not quite working - the comment is still truncating part of the default value:

/**
 * @param {string} [somebody=John Doe] - Somebody's name.
 */

leads to:

tag.comment: 'Doe] - Somebody's name.',

[sandersn]

Typescript's jsdoc parser doesn't support default values, only types. In addition, the value syntax of default values isn't the same as TS's value syntax -- the string isn't quoted, for example.

One heavy-weight workaround is to get the text of the entire node and parse it yourself -- I can't remember the best API to get the text of a node, but in scripts I've used sourceFile.text.slice(tag.pos, tag.end).

Edit: I looked at the code. It actually does parse default values, but it uses parseExpression, which parses only typescript expressions.

[atanasster]

Thank you very much for the lead, I was able to somewhat work around - tag.getText() gives the full tag string

@param {string} [somebody=John Doe] - Somebody's name.

and with re extract the default value like:

  const fullTagText = tag.getText();
  const defaultValue = /\[.*\=(.*)\]/g.exec(fullTagText);
  if (defaultValue?.[1]) {
    prop.value = defaultValue[1];
  }

I can also fix the comment to remove the starting default value remains after the space:
Doe] - Somebody's name. -> Somebody's name.

Do you think it also makes sense to remove the starting '-' hyphen from the comment?

Btw - can you please give me a working example of default value working with a typescript expression, I was unable to come up with one.

[sandersn]

Btw - can you please give me a working example of default value working with a typescript expression, I was unable to come up with one.

This works for me: https://ts-ast-viewer.com/#code/PQKhAIAEAcEMCdYFtwG0AeBeAjAXXACYAshysA5gKbgjABQAZgK4B2AxgC4CWA9i+EgAU6cJnDYAlOADe4AL50gA

It's hard to tell because the tag doesn't save the default value. It just parses it and moves on. That's a separate, but prerequisite, problem to your original one. I assume that you'd like the default value present in the param tag?

Do you think it also makes sense to remove the starting '-' hyphen from the comment?

I don't have a strong opinion, although I prefer to avoid processing comment text without a compelling reason. You could create another issue and try to get a discussion going among people who work with editors more.

[atanasster]

This works for me: https://ts-ast-viewer.com/#code/PQKhAIAEAcEMCdYFtwG0AeBeAjAXXACYAshysA5gKbgjABQAZgK4B2AxgC4CWA9i+EgAU6cJnDYAlOADe4AL50gA

Got, it - I was trying to make it work with pure jsdoc, ie:

/** @param {number} [x=1] d4 damage */
export function m(x) {}

I don't have a strong opinion, although I prefer to avoid processing comment text without a compelling reason.

I understand and will create a new suggestion, as it seems the space-hyphen-space is a standard description separator : https://jsdoc.app/tags-param.html