microsoft / microsoft/TypeScript

JSDoc optional property in object

Open
#39,906 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Domain: JSDoc
Dominant language
Go
Stars
111k
Forks
14.3k
Avg merge
2d 4h
Merged PRs (30d)
132

Description

TypeScript Version: 3.9.x & 4.1.x

Search Terms: jsdoc optional

There seems to be a regression since version 3.9.x where optional params in JSDocs are not converted correctly in declaration files. Several issues were created (linked below) and patches were made, however, it seems that params nested inside objects are still not correctly handled as optional when surrounded by brackets.

Code

/**
 * Does Foo
 *
 * @param {object} opts
 * @param {string} [opts.bar] - is optional
 * @returns void
 */
function foo(opts ) {
  // ..
}

Expected behavior: (as well as actual behavior <=3.8.3)

declare function foo(opts: {
    bar?: string;
}): void;

Actual behavior:

declare function foo(opts: {
    bar: string;
}): void;

Related Issues:
https://github.com/microsoft/TypeScript/issues/39111 was addressed with https://github.com/microsoft/TypeScript/pull/39487, but it doesn't seem that nested properties were covered in that fix.
https://github.com/microsoft/TypeScript/pull/39123 and https://github.com/microsoft/TypeScript/pull/39457 seem to relate to Closure notation, not sure if they're related.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the provided JSDoc example with TypeScript 3.9.x and 4.1.x, comparing the emitted declaration with the expected optional nested property. Then read issue #39111 and pull request #39487 to understand the related fix; done means nested bracketed properties emit with ? in the declaration.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript
Domain
compilers
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.