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...