search

bufbuild / protobuf-es

Protocol Buffers for ECMAScript. The only JavaScript Protobuf library that is fully-compliant with Protobuf conformance tests.
Apache License 2.0
1.16k stars 69 forks source link

Generated JSON types should include @deprecated in doc comment like the main types #971

Closed ngbrown closed 2 months ago

ngbrown commented 2 months ago

When the protoc-gen-es plugin is ran with the json_types=true option, the generated jsdoc comment does not currently include @deprecated when the proto field is marked as deprecated ([deprecated = true]) while the main types do.

The generated JSON type should include @deprecated in the jsdoc comment as well.

@bufbuild/buf: 1.41.0 @bufbuild/protoc-gen-es: 2.0.0

timostamm commented 2 months ago

That's a good call. Currently, we generate this JSDoc block for a JSON type for a message:

/**
 * JSON type for the message example.User.
 */

We don't include the original comment, a @deprecated tag, or the @generated from ... annotation that we generate for the primary type for a message.

The same is likely true for enumerations, and probably also for fields. Repeating all comments increases the size of the generated files - not ideal, but they are all types, and having comments available all the time is most likely worth it.

The only thing that's still unclear to me is how we can effectively let users know about the distinction between the primary type, and the JSON type if we no longer have the single, short comment.