search

golang / protobuf

Go support for Google's protocol buffers
BSD 3-Clause "New" or "Revised" License
9.76k stars 1.58k forks source link

protoc-gen-go: add doc comment to String method to explain its output isn't stable #1332

Open meling opened 3 years ago

meling commented 3 years ago

Is your feature request related to a problem? Please describe.

I wrote code as part of an Example style test that used the generated String() method, forgetting about issue #1121. While it shouldn't have taken me long to figure out this, it did! (I was focused on trying to understand the code that caused instability, and didn't read the doc comment on the Format() method, until much too late.)

Describe the solution you'd like

It would help if a doc comment had surfaced this from the generated messages' String() methods.

// String returns the message as a string.
// This method is only intended for human consumption and ignores errors.
// Do not depend on the output being stable. It may change over time across
// different versions of the program.

I guess the doc comment could be written more briefly if the number of comment lines is a concern.

dsnet commented 3 years ago

In addition to concerns about duplication of this same messaging on every generated message, I suspect that most calls to the String method do not happen directly, but indirectly through fmt.Printf and another functionality that understand the fmt.Stringer interface.