Referenced function types inserts complete function documentation in parameter list

[LeviticusMB]

Search terms

Function arguments.

Expected Behavior

I expect a functions parameters to be documented using just the text included in @param.

Actual Behavior

When a function parameter is typeof aFunction or has a default function value, the complete documentation if the referenced function is included in the parameter description.

Steps to reproduce the bug

refbug.ts:

/**
 * This is a plain function that turns its argument into uppercase.
 *
 * @param   value The value to make uppercase
 * @returns The value in uppercase.
 */
export function func(value: string) {
    return value.toUpperCase();
}

/**
 * This is a function namespace.
 *
 * @returns An array containing the string `ns`.
 */
export function ns() {
    return ['ns'];
}

/**
 * This is a namespaced function that returns its argument uppercased and wrapped in a String object.
 *
 * @param   value The value to turn into uppercase and wrap in a String object.
 * @returns The provied value, turned into uppercase letters only, as a String object.
 */
ns.nsFunc = function nsFunc(value: string) {
    return new String(value.toLocaleLowerCase())
}

/**
 * A function with default params.
 *
 * @param funcArg   A normal function argument.
 * @param nsArg     A function namespace default.
 * @param nsFuncArg A namespaced function default.
 */
export function refbug(funcArg: typeof func, nsArg = ns, nsFuncArg = ns.nsFunc) {
}

tsconfig.json:

{
    "include": [ "*.ts" ]
}

package.json:

{
  "dependencies": {
    "typedoc": "^0.24.7",
    "typedoc-plugin-markdown": "^3.15.3"
  }
}

Run with

rm -rf docs && pnpm typedoc --entryPoints refbug.ts  --tsconfig tsconifg.json

The generated documentation for the refbug function now includes the complete docs for func and nsFunc (but not ns!).

When using the typedoc-plugin-markdown, it's even worse since the actual @param documentation is completely missing.

rm -rf docs && pnpm typedoc --entryPoints refbug.ts  --tsconfig tsconifg.json  --plugin typedoc-plugin-markdown

Environment

• Typedoc version: 0.24.7
• TypeScript version: -
• Node.js version: v16.20.0
• OS: macOS Ventura 13.1

[Gerrit0]

Hmm, this is going to be somewhat tricky to resolve, because the comment there is being picked up by the logic to handle APIs which use a factory that returns a documented function:

function factory() {
  /** Docs */
  return function() {}
}

export const thing = factory();

[jstritch]

What is the use case for fully documenting a function passed as a parameter to another function? Is the use case recursive?

[Gerrit0]

This is a really weird bug. I wasn't right back in May. This happens because TypeDoc goes to convert the parameter's type, notices it is a function, so goes to convert the signature type... but the signature declaration, unlike the normal cases, is actually present describing a real function, not just some type node.... which means that TypeDoc adds a comment to the signature, as it should.. it's literally hitting the normal function documentation case.

It doesn't happen to the ns case because that isn't just a simple function, but a function+...

I can't/shouldn't just disable adding comments because in the following case, the comment should show up

function foo(cb: {
  /** Docs! */
  (): string;
}) {}

All that to say, I'm not seeing a good way of detecting this case. I guess I could check to see if the signature declaration location is outside of the parent function declaration that we're converting, but that is a terrible check and probably misses things... I'm leaning towards marking this as a design limitation.