Skip to content

fix: keep brackets at the start of a nameless tag description - #274

Open
TheeCoderAhmed wants to merge 1 commit into
fardad-dev:masterfrom
TheeCoderAhmed:fix/nameless-tag-leading-brackets
Open

TheeCoderAhmed wants to merge 1 commit into
fardad-dev:masterfrom
TheeCoderAhmed:fix/nameless-tag-leading-brackets

Conversation

@TheeCoderAhmed

Copy link
Copy Markdown

Fixes #269

What breaks

A nameless tag whose description starts with [ gets rewritten, and its type gets widened:

/**
 * @returns {number[]} [x, y]
 */

becomes

/**
 * @returns {number[] | undefined} X, y
 */

Why

comment-parser reads a leading [x, y] as an optional name, so the tag comes back with name: "x, y" and optional: true. normalizeTags folds that name back into the description for tags in TAGS_NAMELESS, but it keeps optional and default and uses the name without its brackets. assignOptionalAndDefaultToName then sees optional with an empty name and appends | undefined.

What changed

When the name is folded into the description, normalizeTags now uses the raw [...] text from the source tokens and clears optional and default. This goes a little past the fix suggested in the issue, because clearing the state alone would still print X, y without the brackets, and the issue expects the input to stay unchanged.

normalizeTags runs before the {string=} conversion, so @returns {string=} text still becomes string | undefined. @param {string} [x=1] is not a nameless tag, so it is not affected.

What I ran

  • yarn install --frozen-lockfile --ignore-scripts with yarn 1.22.22 on Node 22.23.
  • tsc --project tsconfig.json, then jest with the ts-node/esm loader: 16 suites, 148 tests, 204 snapshots pass. The new test in tests/main.test.ts failed before the change with @returns {number[] | undefined} X, y.
  • eslint --ext .ts ./src, and prettier --check on the two changed files.
  • A throwaway script formatting @default, @defaultValue, @example, @description, @deprecated, @throws, @returns {string=} and @param inputs through the built plugin, to check the output by eye. It is not part of this PR.

I did not run the CI matrix of other Node and Prettier versions, and I did not run yarn test itself, since it also runs the build script.

comment-parser reads a leading [x] as an optional name. Nameless tags folded
that name into the description, but kept the optional and default state and
dropped the brackets, so @returns {number[]} [x, y] became
@returns {number[] | undefined} X, y. Use the raw text and clear that state.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Nameless tags: description starting with [ is parsed as an optional name and widens the type with | undefined

1 participant