Merge pull request #49 from steved-stripe/steved-include-comments

update codegen to include comments
coinbase · Apr 15, 2024 · 87afd7a · 87afd7a
2 parents f96debe + 3ae69e1
commit 87afd7a
Show file tree

Hide file tree

Showing 16 changed files with 98 additions and 5 deletions.
diff --git a/main.go b/main.go
@@ -58,10 +58,13 @@ func (m *rbiModule) InitContext(c pgs.BuildContext) {
 		"willGenerateInvalidRuby":  m.willGenerateInvalidRuby,
 		"rubyPackage":              ruby_types.RubyPackage,
 		"rubyMessageType":          ruby_types.RubyMessageType,
+		"rubyMessageTypeComment":   ruby_types.RubyMessageTypeComment,
+		"rubyFieldTypeComment":     ruby_types.RubyFieldTypeComment,
 		"rubyGetterFieldType":      ruby_types.RubyGetterFieldType,
 		"rubySetterFieldType":      ruby_types.RubySetterFieldType,
 		"rubyInitializerFieldType": ruby_types.RubyInitializerFieldType,
 		"rubyFieldValue":           ruby_types.RubyFieldValue,
+		"rubyMethodTypeComment":    ruby_types.RubyMethodTypeComment,
 		"rubyMethodParamType":      ruby_types.RubyMethodParamType,
 		"rubyMethodReturnType":     ruby_types.RubyMethodReturnType,
 		"hideCommonMethods":        m.HideCommonMethods,
@@ -134,7 +137,8 @@ func main() {
 const tpl = `# Code generated by protoc-gen-rbi. DO NOT EDIT.
 # source: {{ .InputPath }}
 # typed: strict
-{{ range .AllMessages }}
+{{ range .AllMessages }}{{ if rubyMessageTypeComment . }}
+# {{ rubyMessageTypeComment . }}{{ end }}
 class {{ rubyMessageType . }}{{ if useAbstractMessage }} < ::Google::Protobuf::AbstractMessage{{ else }}
   include ::Google::Protobuf::MessageExts
   extend ::Google::Protobuf::MessageExts::ClassMethods
@@ -175,15 +179,18 @@ class {{ rubyMessageType . }}{{ if useAbstractMessage }} < ::Google::Protobuf::A
 {{ else }}
   sig {void}
   def initialize; end
-{{ end }}{{ range .Fields }}
+{{ end }}{{ range .Fields }}{{ if rubyFieldTypeComment . }}
+  # {{ rubyFieldTypeComment . }}{{ end }}
   sig { returns({{ rubyGetterFieldType . }}) }
   def {{ .Name }}
   end
-
+{{ if rubyFieldTypeComment . }}
+  # {{ rubyFieldTypeComment . }}{{ end }}
   sig { params(value: {{ rubySetterFieldType . }}).void }
   def {{ .Name }}=(value)
   end
-
+{{ if rubyFieldTypeComment . }}
+  # {{ rubyFieldTypeComment . }}{{ end }}
   sig { void }
   def clear_{{ .Name }}
   end
@@ -245,7 +252,8 @@ module {{ rubyPackage .File }}::{{ .Name }}
     end
     def initialize(host, creds, **kw)
     end{{ range .Methods }}
-
+{{ if rubyMethodTypeComment . }}
+    # {{ rubyMethodTypeComment . }}{{ end }}
     sig do
       params(
         request: {{ rubyMethodParamType . }}

diff --git a/ruby_types/ruby_types.go b/ruby_types/ruby_types.go
@@ -42,6 +42,18 @@ func RubyPackage(file pgs.File) string {
 	return upperCamelCase(pkg)
 }
 
+func escapeRubyComment(comment string) string {
+	return strings.ReplaceAll(comment, "\n", "\n#")
+}
+
+func RubyFieldTypeComment(field pgs.Field) string {
+	return escapeRubyComment(strings.TrimSpace(field.SourceCodeInfo().LeadingComments()))
+}
+
+func RubyMessageTypeComment(entity EntityWithParent) string {
+	return escapeRubyComment(strings.TrimSpace(entity.SourceCodeInfo().LeadingComments()))
+}
+
 func RubyMessageType(entity EntityWithParent) string {
 	names := make([]string, 0)
 	outer := entity
@@ -214,6 +226,10 @@ func rubyMapType(ft FieldType) string {
 	return ""
 }
 
+func RubyMethodTypeComment(method pgs.Method) string {
+	return escapeRubyComment(strings.TrimSpace(method.SourceCodeInfo().LeadingComments()))
+}
+
 func RubyMethodParamType(method pgs.Method) string {
 	return rubyMethodType(method.Input(), method.ClientStreaming())
 }

diff --git a/testdata/all/example_pb.rbi b/testdata/all/example_pb.rbi
@@ -2,6 +2,7 @@
 # source: example.proto
 # typed: strict
 
+# some description for request message
 class Example::Request < ::Google::Protobuf::AbstractMessage
   sig do
     params(
@@ -13,19 +14,24 @@ class Example::Request < ::Google::Protobuf::AbstractMessage
   )
   end
 
+  # some description for name field
   sig { returns(String) }
   def name
   end
 
+  # some description for name field
   sig { params(value: String).void }
   def name=(value)
   end
 
+  # some description for name field
   sig { void }
   def clear_name
   end
 end
 
+# some description for responsee message that is multi line and has a # in it
+# that needs to be escaped
 class Example::Response < ::Google::Protobuf::AbstractMessage
   sig do
     params(
@@ -37,14 +43,17 @@ class Example::Response < ::Google::Protobuf::AbstractMessage
   )
   end
 
+  # some description for greeting field
   sig { returns(String) }
   def greeting
   end
 
+  # some description for greeting field
   sig { params(value: String).void }
   def greeting=(value)
   end
 
+  # some description for greeting field
   sig { void }
   def clear_greeting
   end

diff --git a/testdata/all/example_services_pb.rbi b/testdata/all/example_services_pb.rbi
@@ -18,6 +18,7 @@ module Example::Greeter
     def initialize(host, creds, **kw)
     end
 
+    # some description for hello rpc
     sig do
       params(
         request: Example::Request

diff --git a/testdata/all/services_services_pb.rbi b/testdata/all/services_services_pb.rbi
@@ -18,6 +18,7 @@ module Testdata::SimpleMathematics
     def initialize(host, creds, **kw)
     end
 
+    # Negates the input
     sig do
       params(
         request: Testdata::Subdir::IntegerMessage
@@ -26,6 +27,7 @@ module Testdata::SimpleMathematics
     def negate(request)
     end
 
+    # Report the median of a stream of integers
     sig do
       params(
         request: T::Enumerable[Testdata::Subdir::IntegerMessage]
@@ -52,6 +54,7 @@ module Testdata::ComplexMathematics
     def initialize(host, creds, **kw)
     end
 
+    # Stream the first N numbers in the Fibonacci sequence
     sig do
       params(
         request: Testdata::Subdir::IntegerMessage
@@ -60,6 +63,7 @@ module Testdata::ComplexMathematics
     def fibonacci(request)
     end
 
+    # Accept a stream of integers, and report whenever a new maximum is found
     sig do
       params(
         request: T::Enumerable[Testdata::Subdir::IntegerMessage]
@@ -68,6 +72,7 @@ module Testdata::ComplexMathematics
     def running_max(request)
     end
 
+    # Accept a stream of integers, and report the maximum every second
     sig do
       params(
         request: T::Enumerable[Testdata::Subdir::IntegerMessage]

diff --git a/testdata/example.proto b/testdata/example.proto
@@ -2,14 +2,21 @@ syntax = "proto3";
 
 package example;
 
+// some description for request message
 message Request {
+  // some description for name field
   string name = 1;
 }
 
+// some description for responsee message that is multi line and has a # in it
+// that needs to be escaped
 message Response {
+  // some description for greeting field
   string greeting = 1;
 }
 
+// some description for greeter service
 service Greeter {
+  // some description for hello rpc
   rpc Hello (Request) returns (Response);
 }
diff --git a/testdata/example_pb.rbi b/testdata/example_pb.rbi
@@ -2,6 +2,7 @@
 # source: example.proto
 # typed: strict
 
+# some description for request message
 class Example::Request
   include ::Google::Protobuf::MessageExts
   extend ::Google::Protobuf::MessageExts::ClassMethods
@@ -36,14 +37,17 @@ class Example::Request
   )
   end
 
+  # some description for name field
   sig { returns(String) }
   def name
   end
 
+  # some description for name field
   sig { params(value: String).void }
   def name=(value)
   end
 
+  # some description for name field
   sig { void }
   def clear_name
   end
@@ -61,6 +65,8 @@ class Example::Request
   end
 end
 
+# some description for responsee message that is multi line and has a # in it
+# that needs to be escaped
 class Example::Response
   include ::Google::Protobuf::MessageExts
   extend ::Google::Protobuf::MessageExts::ClassMethods
@@ -95,14 +101,17 @@ class Example::Response
   )
   end
 
+  # some description for greeting field
   sig { returns(String) }
   def greeting
   end
 
+  # some description for greeting field
   sig { params(value: String).void }
   def greeting=(value)
   end
 
+  # some description for greeting field
   sig { void }
   def clear_greeting
   end

diff --git a/testdata/example_services_pb.rb b/testdata/example_services_pb.rb
diff --git a/testdata/example_services_pb.rbi b/testdata/example_services_pb.rbi
@@ -18,6 +18,7 @@ module Example::Greeter
     def initialize(host, creds, **kw)
     end
 
+    # some description for hello rpc
     sig do
       params(
         request: Example::Request

diff --git a/testdata/hide_common_methods/example_pb.rbi b/testdata/hide_common_methods/example_pb.rbi
@@ -2,6 +2,7 @@
 # source: example.proto
 # typed: strict
 
+# some description for request message
 class Example::Request
   include ::Google::Protobuf::MessageExts
   extend ::Google::Protobuf::MessageExts::ClassMethods
@@ -16,19 +17,24 @@ class Example::Request
   )
   end
 
+  # some description for name field
   sig { returns(String) }
   def name
   end
 
+  # some description for name field
   sig { params(value: String).void }
   def name=(value)
   end
 
+  # some description for name field
   sig { void }
   def clear_name
   end
 end
 
+# some description for responsee message that is multi line and has a # in it
+# that needs to be escaped
 class Example::Response
   include ::Google::Protobuf::MessageExts
   extend ::Google::Protobuf::MessageExts::ClassMethods
@@ -43,14 +49,17 @@ class Example::Response
   )
   end
 
+  # some description for greeting field
   sig { returns(String) }
   def greeting
   end
 
+  # some description for greeting field
   sig { params(value: String).void }
   def greeting=(value)
   end
 
+  # some description for greeting field
   sig { void }
   def clear_greeting
   end

diff --git a/testdata/hide_common_methods/example_services_pb.rbi b/testdata/hide_common_methods/example_services_pb.rbi
@@ -18,6 +18,7 @@ module Example::Greeter
     def initialize(host, creds, **kw)
     end
 
+    # some description for hello rpc
     sig do
       params(
         request: Example::Request

diff --git a/testdata/hide_common_methods/services_services_pb.rbi b/testdata/hide_common_methods/services_services_pb.rbi
@@ -18,6 +18,7 @@ module Testdata::SimpleMathematics
     def initialize(host, creds, **kw)
     end
 
+    # Negates the input
     sig do
       params(
         request: Testdata::Subdir::IntegerMessage
@@ -26,6 +27,7 @@ module Testdata::SimpleMathematics
     def negate(request)
     end
 
+    # Report the median of a stream of integers
     sig do
       params(
         request: T::Enumerable[Testdata::Subdir::IntegerMessage]
@@ -52,6 +54,7 @@ module Testdata::ComplexMathematics
     def initialize(host, creds, **kw)
     end
 
+    # Stream the first N numbers in the Fibonacci sequence
     sig do
       params(
         request: Testdata::Subdir::IntegerMessage
@@ -60,6 +63,7 @@ module Testdata::ComplexMathematics
     def fibonacci(request)
     end
 
+    # Accept a stream of integers, and report whenever a new maximum is found
     sig do
       params(
         request: T::Enumerable[Testdata::Subdir::IntegerMessage]
@@ -68,6 +72,7 @@ module Testdata::ComplexMathematics
     def running_max(request)
     end
 
+    # Accept a stream of integers, and report the maximum every second
     sig do
       params(
         request: T::Enumerable[Testdata::Subdir::IntegerMessage]