Trailing comments are not properly compiled

[Zamiell]

protobuf-ts does not properly convert comments to JSDoc format.

For example, the following proto code:

message PortSet {
  optional int32 game_port = 1; // It is extremely important that you do not use port 0 for this field or the universe will implode.
  optional int32 base_port = 2;
}

Get compiled to this:

/**
 * @generated from protobuf message SC2APIProtocol.PortSet
 */
export interface PortSet {
    /**
     * @generated from protobuf field: optional int32 game_port = 1;
     */
    gamePort?: number; // It is extremely important that you do not use port 0 for this field or the universe will implode.
    /**
     * @generated from protobuf field: optional int32 base_port = 2;
     */
    basePort?: number;
}

As you can see, the comment annotation for the game_port field is not included in the JSDoc comment. Instead, it is stuck on the side as a "normal" comment.

This is a problem, because in VSCode (the most common IDE for TypeScript), when I mouse over the gamePort field, all I see in the mouseover documentation is the JSDoc comment. Non-JSDoc comments are never included in the mouseover documentation, which means that in this case, this extremely important information is hidden from me and all of my end-users who consume this interface, and the fate of the universe is in the balance.

Instead, protobuf-ts should convert // comments to JSDoc comments, and add to the existing JSDoc comment if it exists.

[timostamm]

protobuf-ts takes the leading (and leading detached) comments for a JSDoc block:

message PortSet {
  // It is extremely important that you do not use port 0 for this field or the universe will implode.
  optional int32 game_port = 1;
  optional int32 base_port = 2;
}

Will be:

    /**
     * It is extremely important that you do not use port 0 for this field or the universe will implode.
     * 
     * @generated from protobuf field: optional int32 game_port = 1;
     */
    gamePort?: number;

Trailing comments (line comment to the right of a symbol) are kept as trailing comments.

[Zamiell]

Thanks for the quick response.

Trailing comments (line comment to the right of a symbol) are kept as trailing comments.

Would you consider re-thinking this behavior?

Consider the following proto file:

message Fruit {
  // Has illegal values of 1, 2, and 3
  int32 apple = 1;
  // Has illegal values of 5, 6, and 7
  int32 pear = 2;
  // Has illegal values of 12, 13, and 14
  int32 banana = 3;
}

With this format, protobuf-ts would helpfully convert all of these comments into JSDoc so that the end-user can see them when hovering over the respective properties in their IDE.

However, I submit to you that not very many people would type out a proto file like this. Instead, I think it would be more common to type out the file like this:

message Fruit {
  int32 apple = 1;  // Has illegal values of 1, 2, and 3
  int32 pear = 2;   // Has illegal values of 5, 6, and 7
  int32 banana = 3; // Has illegal values of 12, 13, and 14
}

This is more compact and much easier to read!

However, now we have a problem: proto-ts creates different output for this second file. All of the helpful information in the comments is "soft-destroyed". I use the term "soft-destroyed" because the information is not really destroyed - it is still there in the source code for the generated TypeScript file. But it is effectively hidden: no-one would know that it is there, because no-one typically reads through auto-generated-code-from-tooling.

To fix this problem, I propose that proto-ts generates equivalent output for both of these hypothetical proto files, always generating JSDoc comments to "preserve" as much as information as possible.

[timostamm]

Thanks for your thoughts, @Zamiell. I think your Fruit example is about the worst case you could have, because none of the comments end up in JSDoc.

What do you suggest to do in case users have specified both leading and trailing comments?

[Zamiell]

What do you suggest to do in case users have specified both leading and trailing comments?

That is an interesting case. I think the two options would be:

1. The leading comment will win, and that will get converted to JSDoc while the trailing comment is ignored.
2. The leading comment is combined with a newline + the trailing comment when converting to JSDoc.

Between these two options, I prefer the latter, but I leave that to you.