chore(internal/protoveneer): doc for fields (#10352)

Add the ability to customize doc comments for struct fields.
googleapis · Jun 21, 2024 · 1d28ac6 · 1d28ac6
1 parent 2003148
commit 1d28ac6
Show file tree

Hide file tree

Showing 5 changed files with 29 additions and 6 deletions.
diff --git a/internal/protoveneer/cmd/protoveneer/config.go b/internal/protoveneer/cmd/protoveneer/config.go
@@ -69,6 +69,7 @@ type typeConfig struct {
 type fieldConfig struct {
  Name string // veneer name
  Type string // veneer type
+ Doc string // Doc string for the field. Replaces existing doc.
  // Omit from output.
  Omit bool
  // This field is not part of the proto; add it.

diff --git a/internal/protoveneer/cmd/protoveneer/protoveneer.go b/internal/protoveneer/cmd/protoveneer/protoveneer.go
@@ -514,6 +514,17 @@ func processField(af *ast.Field, tc *typeConfig, typeInfos map[string]*typeInfo)
  }
  af.Type = expr
  }
+ if fc.Doc != "" {
+ cg := &ast.CommentGroup{}
+ for i, line := range strings.Split(strings.TrimSpace(fc.Doc), "\n") {
+ c := &ast.Comment{Text: "// " + line}
+ if i == 0 {
+ c.Slash = af.Pos() - 1
+ }
+ cg.List = append(cg.List, c)
+ }
+ af.Doc = cg
+ }
  if fc.ConvertToFrom != "" {
  c, err := parseCustomConverter(id.Name, fc.ConvertToFrom)
  if err != nil {

diff --git a/internal/protoveneer/cmd/protoveneer/testdata/basic/basic.pb.go b/internal/protoveneer/cmd/protoveneer/testdata/basic/basic.pb.go
@@ -96,9 +96,10 @@ type GenerationConfig struct {
  // Optional. Stop sequences.
  StopSequences []string `protobuf:"bytes,6,rep,name=stop_sequences,json=stopSequences,proto3" json:"stop_sequences,omitempty"`
  HarmCat HarmCategory
- FinishReason Candidate_FinishReason
- CitMet *CitationMetadata
- TopK *float32
+ // Bad doc that doesn't make sense.
+ FinishReason Candidate_FinishReason
+ CitMet *CitationMetadata
+ TopK *float32
 }
 
 // A collection of source attributions for a piece of content.

diff --git a/internal/protoveneer/cmd/protoveneer/testdata/basic/config.yaml b/internal/protoveneer/cmd/protoveneer/testdata/basic/config.yaml
@@ -40,6 +40,12 @@ types:
  TopK:
  type: '*int32'
  convertToFrom: int32pToFloat32p, float32pToInt32p
+ doc: |
+ Multiple lines of
+ documentation for this
+ field.
+ FinishReason:
+ doc: 'The reason for finishing.'
 
  Citation:
  docVerb: contains

diff --git a/internal/protoveneer/cmd/protoveneer/testdata/basic/golden b/internal/protoveneer/cmd/protoveneer/testdata/basic/golden
@@ -177,9 +177,13 @@ type GenerationConfig struct {
  // Optional. Stop sequences.
  StopSequences []string
  HarmCat HarmCategory
- FinishReason FinishReason
- CitMet *CitationMetadata
- TopK *int32
+ // The reason for finishing.
+ FinishReason FinishReason
+ CitMet *CitationMetadata
+ // Multiple lines of
+ // documentation for this
+ // field.
+ TopK *int32
 }
 
 func (v *GenerationConfig) toProto() *pb.GenerationConfig {