Documentation for function variables was not inferred

[JasonHK]

Search terms

const, function

Expected Behavior

Documentation for function variables should be inferred, i.e. the description, parameter descriptions etc. should be inherited.

interface Callable
{
    /**
     * Convert a number to a string.
     * 
     * @param payload A number.
     */
    (payload: number): string;

    /**
     * Convert a string to a number.
     * 
     * @param payload A string.
     */
    (payload: string): number;
}

export declare const callable: Callable;

Actual Behavior

Steps to reproduce the bug

Please refer to the code snippet above.

Environment

• Typedoc version: 0.20.28
• TypeScript version: 4.1.5
• Node.js version: 14.15.5
• OS: Kubuntu 20.04

[Gerrit0]

This is a really tricky one.

We could technically achieve this by relying on symbol.getDocumentationComment() in order to retrieve the comments... but unfortunately this directly conflicts with some other goals, since then comments on elements using declaration merging would show up in both places:

/** NS docs */
namespace Foo {}
/** Function docs */
function Foo() {}

I also wonder... what's the right solution in a case like this?

/** Does this get ignored? What it if includes important info like @hidden? */
export const callable: Callable = ...

I should really write down somewhere what TypeDoc currently does for comments so that it's easier to propose refinements to what it does...

[JasonHK]

This is a really tricky one.

We could technically achieve this by relying on symbol.getDocumentationComment() in order to retrieve the comments... but unfortunately this directly conflicts with some other goals, since then comments on elements using declaration merging would show up in both places:

/** NS docs */
namespace Foo {}
/** Function docs */
function Foo() {}

I also wonder... what's the right solution in a case like this?

/** Does this get ignored? What it if includes important info like @hidden? */
export const callable: Callable = ...

I should really write down somewhere what TypeDoc currently does for comments so that it's easier to propose refinements to what it does...

@Gerrit0 I think TypeDoc should at least inherit tags like @template, @param, @returns and @throws.

[Gerrit0]

Inheritance isn't the tricky part - we already do that for normal interface/class members. The tricky part is inherit from where? There is no implements clause here.

[Gerrit0]

In 0.23, TypeDoc tries to get docs from the signature itself, and therefore picks these up.