protobuf-ts icon indicating copy to clipboard operation
protobuf-ts copied to clipboard

Trailing comments are not properly compiled

Open Zamiell opened this issue 2 years ago • 4 comments

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.

Zamiell avatar Apr 22 '22 23:04 Zamiell