Improve rendering of unions of object literals

[xuhdev]

Search Terms

react component, union

Problem

When the param is a union of object literals, @param fails to document the property names. For example, typedoc would not output the doc after options.northPole and options.southPole.

/**
 * @param options - Magnet options.
 * @param options.northPole - The North Pole. Although optional, but must appear with South Pole.
 * @param options.southPole - The North Pole. Although optional, but must appear with North Pole.
 */
function Magnet({
  northPole,
  southPole,
}:
  | { northPole: number; southPole: number }
  | { northPole?: undefined; southPole?: undefined }) {}

Context

This is possible to encounter likely in a React component. One possible solution is to rewrite the above as overloads. However, depending on the context, it may not be desirable to do so. In fact, the ESLint typescript plugin has a rule "unified signatures" that disfavor splitting into overloads.

[Gerrit0]

This is... super ugly to actually implement. TypeDoc already copies comments to the reflections for both instances of northPole, so this would just be a rendering change... but it's a rendering change where you either have to just render every possible instance of the union (rendering comments multiple times) or somehow decide to just render one branch of the union... or go through every member of the union and just render each possible property once...

[Oblarg]

I think this should probably be merged with #2303? Both of these are probably unsolvable without additional user-supplied metadata regarding the intended interpretation of the type structure, and the metadata they require has substantial overlap.

[Gerrit0]

This is a different issue, slightly related yes, but the implementation will be somewhat different.

[Gerrit0]

Current beta branch: