intellisense for JSDocs on function overloads without needing to duplicate the JSDoc

[mesqueeb]

Suggestion

🔍 Search Terms

• intellisense for JSDocs on function overloads without needing to duplicate the JSDoc
• auto complete
• JSDocs
• function overloads

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

When you have a really long JSDoc that describes a function (say 10+ lines) and you need 3~4 function overloads for that function. The only way to properly have the JSDocs show up on all overload cases when you actually import and use the function is to duplicate the JSDocs for each single function overload...

FR: We need VSCode intellisense for our JSDocs to show up on ALL function overloads without needing to duplicate the JSDocs on every overload.

📃 Motivating Example

Here is a very common example I use countless of times throughout my code where an object that's potentially undefined is parsed in a function, but when we know the payload is not undefined we want to make sure the return type is also not.

type Person = { firstName: string; lastName: string }
type PersonParsed = { fullName: string }

export function parsePerson(person: Person): PersonParsed
export function parsePerson(person: undefined): undefined
export function parsePerson(person: Person | undefined): PersonParsed | undefined
export function parsePerson(person?: Person): PersonParsed | undefined {
  // ... implementation
}

A perfect use-case for function overloads! But then comes your detailed JSDoc and it will look like this:

type Person = { firstName: string; lastName: string }
type PersonParsed = { fullName: string }

/**
 * Here is a very long JSDoc
 *
 * Maybe it describes what the function can do / when it should be used
 * - Maybe it has
 * - some bullet lists
 *
 * @see https://some-related-documentation...
 * @example
 * ```js
 * // some usage examples:
 * const { fullname } = parsePerson(person) || {}
 * console.log(`fullname → `, fullname)
 * ```
 */
export function parsePerson(person: Person): PersonParsed
/**
 * Here is a very long JSDoc
 *
 * Maybe it describes what the function can do / when it should be used
 * - Maybe it has
 * - some bullet lists
 *
 * @see https://some-related-documentation...
 * @example
 * ```js
 * // some usage examples:
 * const { fullname } = parsePerson(person) || {}
 * console.log(`fullname → `, fullname)
 * ```
 */
export function parsePerson(person: undefined): undefined
/**
 * Here is a very long JSDoc
 *
 * Maybe it describes what the function can do / when it should be used
 * - Maybe it has
 * - some bullet lists
 *
 * @see https://some-related-documentation...
 * @example
 * ```js
 * // some usage examples:
 * const { fullname } = parsePerson(person) || {}
 * console.log(`fullname → `, fullname)
 * ```
 */
export function parsePerson(person: Person | undefined): PersonParsed | undefined
/**
 * Here is a very long JSDoc
 *
 * Maybe it describes what the function can do / when it should be used
 * - Maybe it has
 * - some bullet lists
 *
 * @see https://some-related-documentation...
 * @example
 * ```js
 * // some usage examples:
 * const { fullname } = parsePerson(person) || {}
 * console.log(`fullname → `, fullname)
 * ```
 */
export function parsePerson(person?: Person): PersonParsed | undefined {
  // ... implementation
}

💻 Use Cases

Use case explained in the previous section.

Conclusion

We need VSCode intellisense for our JSDocs to show up on ALL function overloads without needing to duplicate the JSDocs on every overload.

[fatcerberus]

Duplicate of #407

[typescript-bot]

This issue has been marked as a 'Duplicate' and has seen no recent activity. It has been automatically closed for house-keeping purposes.

[mesqueeb]

@typescript-bot i think you need to close it as duplicate (the grey one) not as completed (the purple one)