Missing comments in union type properties

[ST-DDT]

Search terms

• union
• comments

Expected Behavior

The jsdocs comments should also be available for union types.

Actual Behavior

Typedoc only attaches the docs for direct reflection/Type literals, but not union types.

Steps to reproduce the bug

/**
 * Method
 *
 * @param options Union Parameter.
 * @param options.min Nested Parameter.
 */
number(options?: number | { min?: number }): number {
  return 0;
}

Expected

{
  "id": 519,
  "name": "number",
  "kind": 2048,
  "kindString": "Method",
  "flags": {},
  "sources": [
    {
      "fileName": "src/test.ts",
      "line": 18,
      "character": 2
    }
  ],
  "signatures": [
    {
      "id": 520,
      "name": "number",
      "kind": 4096,
      "kindString": "Call signature",
      "flags": {},
      "comment": {
        "shortText": "Method"
      },
      "parameters": [
        {
          "id": 521,
          "name": "options",
          "kind": 32768,
          "kindString": "Parameter",
          "flags": {
            "isOptional": true
          },
          "comment": {
            "shortText": "Union Parameter."
          },
          "type": {
            "type": "union",
            "types": [
              {
                "type": "intrinsic",
                "name": "number"
              },
              {
                "type": "reflection",
                "declaration": {
                  "id": 522,
                  "name": "__type",
                  "kind": 65536,
                  "kindString": "Type literal",
                  "flags": {},
                  "children": [
                    {
                      "id": 523,
                      "name": "min",
                      "kind": 1024,
                      "kindString": "Property",
                      "flags": {
                        "isOptional": true
                      },
+                      "comment": {
+                        "shortText": "Nested Parameter.\n"
+                      },
                      "sources": [
                        {
                          "fileName": "src/test.ts",
                          "line": 18,
                          "character": 31
                        }
                      ],
                      "type": {
                        "type": "intrinsic",
                        "name": "number"
                      }
                    }
                  ],
                  "groups": [
                    {
                      "title": "Properties",
                      "kind": 1024,
                      "children": [523]
                    }
                  ]
                }
              }
            ]
          }
        }
      ],
      "type": {
        "type": "intrinsic",
        "name": "number"
      }
    }
  ]
}

Note:

It works if I change the method signature to:

number(options?: { min?: number }): number {

Environment

• Typedoc version: ~0.22.12
• TypeScript version: ~4.5.5
• Node.js version: v16.14.0
• OS: Windows 11

[Gerrit0]

This seems like it will end up as a design limitation to me. The potential for ambiguity is really high.

/**
 * @param options.min What does this get applied to?
 */
function foo(options: { min: number, max: number } | { min: () => number }) {
  return 0;
}

You can put a comment directly on the type declaration, and that should then be picked up:

/**
 * Method
 *
 * @param options Union Parameter.
 */
number(options?: number | { /** Min comment */ min?: number }): number {
  return 0;
}

[ST-DDT]

This seems like it will end up as a design limitation to me. The potential for ambiguity is really high.

/**
 * @param options.min What does this get applied to?
 */
function foo(options: { min: number, max: number } | { min: () => number }) {
  return 0;
}

IMO it wouldn't hurt if the comment gets applied to both, as the parameter usually still does the same.
If the users explicitly want to set it only for one case, they can configure it using the second approach then.
That way it would cover the majority of the cases by default, while still supporting edge cases.

[Gerrit0]

Hmm... that doesn't seem horrible...