protoc-gen-go: indicate deprecated fields in documentation #506
Conversation
|
Not really familiar with how these are processed by the tooling. Adding a comment to the getters might be redundant if using the underlying deprecated field in any call path triggers |
|
@tsl0922 sorry for the noise on the original issue. Thoughts on this? |
protoc-gen-go/generator/generator.go
Outdated
| // Generate deprecation comments for getters as well. | ||
| g.P("// Deprecated: ", mname, " should not be used by new code.") | ||
| g.P("// Underlying field is marked as [deprecated=true] in ", g.file.Name) | ||
| g.P("//") |
There was a problem hiding this comment.
Is the 2 lines above needed? The end users may not care about the proto definition here.
There was a problem hiding this comment.
Is it needed? I don't know. I thought it would be useful to explain why a field is deprecated, but the only reason that it is deprecated is because of the proto definition. I don't have a strong opinion either way. It seems like for the sake of documentation, the user might go look at the underlying field they were trying to get and then find the getter documentation fairly redundant. I'll probably remove this.
|
According to descriptor.proto, deprecation can be applied at multiple levels: file, message, field, enum, enum value, service, and method. Where to put the comment is clear for most of these:
The difficult one is file. Since multiple proto files can go into a single Go package, you cant simply put the "Deprecated" tag in the package comment header. Given the verbosity. I'm okay if all it said was "Deprecated: Do not use." |
|
Please take another look. Newest commit handles all possible deprecated elements in a proto file as you described above. For services, this PR also emits deprecation comments on the |
| @@ -0,0 +1,58 @@ | |||
| // Go support for Protocol Buffers - Google's data interchange format | |||
| // | |||
| // Copyright 2010 The Go Authors. All rights reserved. | |||
There was a problem hiding this comment.
Wheeeee... Time travel. Let's party like its 2010.
|
|
||
| option deprecated = true; // file-level deprecation | ||
|
|
||
| message DeprecatedRequest { |
There was a problem hiding this comment.
Add comment above each message, field, enum, etc to test the ordering of whether "Deprecated: " appears above, below, or inline relative to the comment.
There was a problem hiding this comment.
For the record, the standard library places the deprecation warning under the comment:
https://golang.org/pkg/compress/flate/#WriteError
There was a problem hiding this comment.
Done, and added test to guarantee superfluous comments are emitted when there aren't any original ones.
protoc-gen-go/generator/generator.go
Outdated
| @@ -1330,7 +1330,11 @@ func (g *Generator) generate(file *FileDescriptor) { | |||
| // Generate the header, including package definition | |||
| func (g *Generator) generateHeader() { | |||
| g.P("// Code generated by protoc-gen-go. DO NOT EDIT.") | |||
| g.P("// source: ", g.file.Name) | |||
| if g.file.GetOptions().GetDeprecated() { | |||
| g.P("// ", g.file.Name, " is deprecated: Do not use.") | |||
protoc-gen-go/generator/generator.go
Outdated
| deprecatedEnum := "" | ||
| if enum.GetOptions().GetDeprecated() { | ||
| // Generate inline enum deprecation comment. | ||
| deprecatedEnum = "// Deprecated: Do not use." |
Tools in the Go ecosystem treat code documented with "Deprecated:" as special for purposes of warning users not to use them. When a file, message, field, enum, enum value, service, or method is marked as deprecated, the generator will emit "// Deprecated: Do not use." comments on all relevant exported Go package information related to the deprecated element. This is an outline of how deprecation of each element effects the generated proto: * file - a comment is added to the top of the generated proto. * message - a comment is added above its type definition. * field, enum, or enum value - a comment is added inline with the defintion. * field - an additional comment is added above the field Getter. * service - a comment is added above generated Client interface and New method. * service - a comment is added above generated Server interface and Registration method. * method - a comment is added above the generated method definition. Fixes #396.
Tools in the Go ecosystem treat code documented with "Deprecated:"
as special for purposes of warning users not to use them. When a
field is marked as "[deprecated=true]", generator will produce a
comment indicating the deprecated status of the field.
Fixes #396.