Trailing trivia removed for some object properties

[RussKie]

TypeScript Version: 1.8.x / Playground

Code

// the export annotations
export function bug() {
    // hello

    // another?

    // return annotation
    return {
        // return object annotation
        outer: {
            // more!
            inner1: { // here too
                // and more

                p1: 'v1', // comment1
                p2: 'v2', // comment2
                p3: 'v3'  // last comment
            } // here?
        } // and here?
    }; // here too?

    // and finally here
}

Playground demo

Expected behavior:
All comments preserved

Actual behavior:
comment1 and comment2 are removed

[yuit]

@RussKie is there a particular reason the comments (// comment1 and // comment2 ) have to be at that particular locations?

Unfortunately, with current comment emit system, there is no way to retrieve them back see for extra information (https://github.com/Microsoft/TypeScript-wiki/pull/140/files#diff-e6f81a9d8df4fb4d787121a242ea6bf1R1336)

[RussKie]

Yes, absolutely there is a reason :)

Imagine a large existing JS codebase which is slowly getting converted to TS. There may be an enum which properties are added over time across different versions:

// jshint ignore: start
export = Common_Constants_Module();

function Common_Constants_Module() {

    var Constants = {
        TOPIC: {
            FROM_CONTAINER: {
                MESSAGE1: "message1",
                MESSAGE2: "message2",       // added in 1.0.1
                MESSAGE3: "message3",       // added in 2.0.0
                MESSAGE4: "message4",       // added in 2.0.0
            },
        },

        TRANSPORT: {
            NONE: "none",                                     // -1
            PAGEBUS: "pagebus",                               // 0
            NATIVE_IFRAME: "native_iframe",                   // 1
            NATIVE_OBJECT: "native_object",                   // 2
            NATIVE_POST_MESSAGE: "native_post_message",       // 3
        },

    };
    return Constants;
}

// jshint ignore:end

Thank you for the link, it is insightful.
The loss of comments is still a regression.

[bcoe]

I'm noting similar behavior for class methods in one of our codebases. As an example, see:

https://github.com/googleapis/nodejs-spanner/blob/master/src/table.ts#L301

Once compiled, using TypeScript 3.4.0, deleteRows and other methods are missing their comments.

This is important to us, because we use jsdoc to generate documentation.

Update

The issue we were seeing is actually related to comments being dropped if they're above an overriden method, rather than the main entry point, e.g., in the case of:

delete(): DropTablePromise;
delete(callback: DropTableCallback): void;
delete(callback?: DropTableCallback): DropTablePromise | void {
  // function body.
}

the comment needs to be above delete(callback?: DropTableCallback): DropTablePromise | void { rather than delete(): DropTablePromise;.

[weswigham]

@sandersn you've talked about @bcoe 's issues before - did we ever come to any kind of conclusion around overload documentation inheritance and/or the @inheritDoc jsdoc tag?

[bcoe]

@weswigham @sandersn would it be worth me opening a new issue, rather than hijacking this issue; since it seems like a different topic?

[weswigham]

Probably, though @sandersn might already be aware of a more appropriate one.

[sandersn]

#407 is the oldest one, I think.