Improve the discovery of the doc comment for symbol (or may be a symbol for a doc comment)

[canonic-epicure]

Search terms

Doc comment

Description

I'm using the excludeNotDocumented option to prevent symbols w/o documentation to appear in the docs.
Sometimes I need to document in the inline object type, for example for function arguments:

        elementPointIsReachable (
            target : ActionTarget, 
            options : { offset : ActionTargetOffset, allowChildren : boolean } | ActionTargetOffset, 
            description? : string
        )

The type of options argument appears as {} in the docs (this is expected, because of the excludeNotDocumented):

Now, to include them in the docs, I'm trying to provide a documentation for the properties:

        elementPointIsReachable (
            target : ActionTarget, options : { /** include */ offset : ActionTargetOffset, /** include */allowChildren : boolean } | ActionTargetOffset, description? : string
        )

The result, however, is the same:

To make it work, the doc comment needs to reside on the separate line, above the symbol:

        elementPointIsReachable (
            target : ActionTarget, options : {
                /** include */
                offset : ActionTargetOffset,
                /** include */
                allowChildren : boolean
            } | ActionTargetOffset, description? : string
        )

This produces:

Expected

I'd expect, that the exact location of the doc comment should be not significant. Under "doc comment" I mean a comment with leading double star: /** */. The doc comment should just precede the symbol it documents, whether on the same line, or on the next line.

Environment

• Typedoc version: 0.22.6
• TypeScript version: 4.4.0
• Node.js version: 12.22
• OS: Ubuntu 18.04

[canonic-epicure]

Side note. In my custom fork, based on TypeDoc 0.17, i was using different heuristic for the excludeNotDocumented option - all properties of object literal types should be included (similar to enums). This is exactly to support the case of documenting the inline object types. Perhaps it should be applied in the current version. If you approve it, I can make a PR for it.

function shouldBeIgnoredAsNotDocumented (node: ts.Declaration, kind: ReflectionKind): boolean {
    // never ignore modules, global, and enum members
    if (kind === ReflectionKind.Module || kind === ReflectionKind.Global || kind === ReflectionKind.EnumMember) {
        return false;
    }

    // do not ignore properties of the object types, that has comment themselves, for example
    //
    // /**
    //  * has docs
    //  */
    //  export SomeType = { prop1 : string }
    //
    // same applies to the inline types for function arguments:
    //
    // function someFunc(arg1 : { prop1 : string, prop2 : number }) {...}
    //
    // The `prop1` from above should be included in the docs, even that it has no documentation
    // Note, that this does not seem to apply to classes and interfaces - for those, even the class/interface
    // has docs, we still want to exclude the undocumented properties
    // Thankfully for object literals the kind of properties seems to be set to ReflectionKind.Variable
    if (kind === ReflectionKind.Variable && hasCommentOnParentAxis(node)) {
        return false;
    }

    const hasComment: boolean = Boolean(getRawComment(node));

    return !hasComment;
}

function hasCommentOnParentAxis (node: ts.Node): boolean {
    let currentNode: ts.Node = node;

    while (currentNode) {
        if (Boolean(getRawComment(currentNode))) { return true; }

        currentNode = currentNode.parent;
    }

    return false;
}

[Gerrit0]

That definitely seems more like how it should work to me, I really dislike that reflections are used for object types in the first place, but haven't gotten around to it.

We rely on ts.getLeadingCommentRanges to extract comments, I suspect that's not being returned for some reason... or maybe properties aren't included in the list of syntax kinds to search for that reflection type.