Merge pull request #137 from sue445/feature/add_github_link

Add GitHub link to generated code

Author: sue445

.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2024-09-18 15:36:12 UTC using RuboCop version 1.66.1.
+# on 2024-09-22 07:12:45 UTC using RuboCop version 1.66.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -9,7 +9,7 @@
 # Offense count: 5
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
 Metrics/AbcSize:
-  Max: 64
+  Max: 67
 
 # Offense count: 1
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
@@ -32,10 +32,10 @@ Metrics/ClassLength:
 Metrics/CyclomaticComplexity:
   Max: 17
 
-# Offense count: 9
+# Offense count: 10
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 58
+  Max: 61
 
 # Offense count: 3
 # Configuration parameters: AllowedMethods, AllowedPatterns.

_tools/ruby_h_to_go/lib/ruby_h_to_go/argument_definition.rb

@@ -3,15 +3,21 @@
 module RubyHToGo
   # Proxy class for generating argument in go function
   class ArgumentDefinition
+    # @!attribute [r] header_dir
+    #   @return [String]
+    attr_reader :header_dir
+
     extend Forwardable
 
     def_delegators :@definition, :==, :type, :type=, :name, :name=, :pointer, :pointer=, :pointer?, :length, :length=
 
     include GeneratorHelper
 
     # @param definition [RubyHeaderParser::ArgumentDefinition]
-    def initialize(definition)
+    # @param header_dir [String]
+    def initialize(definition:, header_dir:)
       @definition = definition
+      @header_dir = header_dir
     end
 
     C_NAME_TO_GO_NAME = {

_tools/ruby_h_to_go/lib/ruby_h_to_go/cli.rb

@@ -38,23 +38,32 @@ def parser
     end
 
     def write_type_definitions_to_go_file
-      type_definitions = parser.extract_type_definitions.map { |d| RubyHToGo::TypeDefinition.new(d) }
+      type_definitions = parser.extract_type_definitions.map do |definition|
+        RubyHToGo::TypeDefinition.new(definition:, header_dir:)
+      end
+
       type_definitions.each do |definition|
-        definition.write_go_file(dist_dir:, header_dir:)
+        definition.write_go_file(dist_dir)
       end
     end
 
     def write_struct_definitions_to_go_file
-      struct_definitions = parser.extract_struct_definitions.map { |d| RubyHToGo::StructDefinition.new(d) }
+      struct_definitions = parser.extract_struct_definitions.map do |definition|
+        RubyHToGo::StructDefinition.new(definition:, header_dir:)
+      end
+
       struct_definitions.each do |definition|
-        definition.write_go_file(dist_dir:, header_dir:)
+        definition.write_go_file(dist_dir)
       end
     end
 
     def write_function_definitions_to_go_file
-      function_definitions = parser.extract_function_definitions.map { |d| RubyHToGo::FunctionDefinition.new(d) }
+      function_definitions = parser.extract_function_definitions.map do |definition|
+        RubyHToGo::FunctionDefinition.new(definition:, header_dir:)
+      end
+
       function_definitions.each do |definition|
-        definition.write_go_file(dist_dir:, header_dir:)
+        definition.write_go_file(dist_dir)
       end
     end
 

_tools/ruby_h_to_go/lib/ruby_h_to_go/function_definition.rb

@@ -3,32 +3,36 @@
 module RubyHToGo
   # Proxy class for generating go function
   class FunctionDefinition
+    # @!attribute [r] header_dir
+    #   @return [String]
+    attr_reader :header_dir
+
     extend Forwardable
 
     def_delegators :@definition, :==, :name, :name=, :definition, :definition=, :filepath, :filepath=
 
     include GeneratorHelper
 
     # @param definition [RubyHeaderParser::FunctionDefinition]
-    def initialize(definition)
+    def initialize(definition:, header_dir:)
       @definition = definition
+      @header_dir = header_dir
     end
 
     # @return [RubyHToGo::TyperefDefinition]
     def typeref
-      @typeref ||= RubyHToGo::TyperefDefinition.new(@definition.typeref)
+      @typeref ||= RubyHToGo::TyperefDefinition.new(definition: @definition.typeref, header_dir:)
     end
 
     # @return [Array<RubyHToGo::ArgumentDefinition>]
     def args
-      @args ||= @definition.args.map { |arg| RubyHToGo::ArgumentDefinition.new(arg) }
+      @args ||= @definition.args.map { |arg| RubyHToGo::ArgumentDefinition.new(definition: arg, header_dir:) }
     end
 
     # Write definition as go file
     # @param [String] dist_dir
-    # @param [String] header_dir
-    def write_go_file(dist_dir:, header_dir:)
-      go_file_path = File.join(dist_dir, go_file_name(header_dir:, ruby_header_file: filepath))
+    def write_go_file(dist_dir)
+      go_file_path = File.join(dist_dir, generate_go_file_name(header_dir:, ruby_header_file: filepath))
 
       generate_initial_go_file(go_file_path)
 
@@ -44,12 +48,16 @@ def generate_go_content
 
       go_function_typeref = typeref.go_function_typeref
 
+      github_url = generate_include_github_url(header_dir:, ruby_header_file: filepath)
+
       go_function_lines = [
         "// #{go_function_name} calls `#{name}` in C",
         "//",
         "// Original definition is following",
         "//",
         "//\t#{definition}",
+        "//",
+        "// ref. #{github_url}",
       ]
 
       go_function_lines << "func #{go_function_name}(#{go_function_args.join(", ")}) #{go_function_typeref} {"

_tools/ruby_h_to_go/lib/ruby_h_to_go/generator_helper.rb

@@ -6,11 +6,20 @@ module GeneratorHelper
     # @param header_dir [String]
     # @param ruby_header_file [String]
     # @return [String]
-    def go_file_name(header_dir:, ruby_header_file:)
+    def generate_go_file_name(header_dir:, ruby_header_file:)
       ruby_header_file.delete_prefix(header_dir + File::SEPARATOR).gsub(File::SEPARATOR, "_").
         gsub(/\.h$/, "_generated.go")
     end
 
+    # Generate GitHub url in https://github.com/ruby/ruby
+    # @param header_dir [String]
+    # @param ruby_header_file [String]
+    # @return [String]
+    def generate_include_github_url(header_dir:, ruby_header_file:)
+      file = ruby_header_file.delete_prefix(header_dir + File::SEPARATOR)
+      "https://github.com/ruby/ruby/blob/master/include/#{file}"
+    end
+
     # @param str [String]
     # @return [String]
     def snake_to_camel(str)

_tools/ruby_h_to_go/lib/ruby_h_to_go/struct_definition.rb

@@ -3,22 +3,27 @@
 module RubyHToGo
   # Proxy class for generating go type
   class StructDefinition
+    # @!attribute [r] header_dir
+    #   @return [String]
+    attr_reader :header_dir
+
     extend Forwardable
 
     def_delegators :@definition, :==, :name, :name=, :filepath, :filepath=
 
     include GeneratorHelper
 
     # @param definition [RubyHeaderParser::StructDefinition]
-    def initialize(definition)
+    # @param header_dir [String]
+    def initialize(definition:, header_dir:)
       @definition = definition
+      @header_dir = header_dir
     end
 
     # Write definition as go file
     # @param [String] dist_dir
-    # @param [String] header_dir
-    def write_go_file(dist_dir:, header_dir:)
-      go_file_path = File.join(dist_dir, go_file_name(header_dir:, ruby_header_file: filepath))
+    def write_go_file(dist_dir)
+      go_file_path = File.join(dist_dir, generate_go_file_name(header_dir:, ruby_header_file: filepath))
 
       generate_initial_go_file(go_file_path)
 
@@ -29,10 +34,14 @@ def write_go_file(dist_dir:, header_dir:)
 
     # @return [String]
     def generate_go_content
+      github_url = generate_include_github_url(header_dir:, ruby_header_file: filepath)
+
       go_type_name = snake_to_camel(name)
 
       <<~GO
         // #{go_type_name} is a type for passing `C.#{name}` in and out of package
+        //
+        // ref. #{github_url}
         type #{go_type_name} C.#{name}
 
       GO

_tools/ruby_h_to_go/lib/ruby_h_to_go/type_definition.rb

@@ -3,22 +3,26 @@
 module RubyHToGo
   # Proxy class for generating go type
   class TypeDefinition
+    # @!attribute [r] header_dir
+    #   @return [String]
+    attr_reader :header_dir
+
     extend Forwardable
 
     def_delegators :@definition, :==, :name, :name=, :filepath, :filepath=
 
     include GeneratorHelper
 
     # @param definition [RubyHeaderParser::TypeDefinition]
-    def initialize(definition)
+    def initialize(definition:, header_dir:)
       @definition = definition
+      @header_dir = header_dir
     end
 
     # Write definition as go file
     # @param [String] dist_dir
-    # @param [String] header_dir
-    def write_go_file(dist_dir:, header_dir:)
-      go_file_path = File.join(dist_dir, go_file_name(header_dir:, ruby_header_file: filepath))
+    def write_go_file(dist_dir)
+      go_file_path = File.join(dist_dir, generate_go_file_name(header_dir:, ruby_header_file: filepath))
 
       generate_initial_go_file(go_file_path)
 
@@ -29,10 +33,14 @@ def write_go_file(dist_dir:, header_dir:)
 
     # @return [String]
     def generate_go_content
+      github_url = generate_include_github_url(header_dir:, ruby_header_file: filepath)
+
       go_type_name = snake_to_camel(name)
 
       <<~GO
         // #{go_type_name} is a type for passing `C.#{name}` in and out of package
+        //
+        // ref. #{github_url}
         type #{go_type_name} C.#{name}
 
       GO

_tools/ruby_h_to_go/lib/ruby_h_to_go/typeref_definition.rb

@@ -3,15 +3,20 @@
 module RubyHToGo
   # Proxy class for generating typeref in go function
   class TyperefDefinition
+    # @!attribute [r] header_dir
+    #   @return [String]
+    attr_reader :header_dir
+
     extend Forwardable
 
     def_delegators :@definition, :==, :type, :type=, :pointer, :pointer=, :pointer?
 
     include GeneratorHelper
 
     # @param definition [RubyHeaderParser::TyperefDefinition]
-    def initialize(definition)
+    def initialize(definition:, header_dir:)
       @definition = definition
+      @header_dir = header_dir
     end
 
     # @return [String]

_tools/ruby_h_to_go/spec/ruby_h_to_go/function_definition_spec.rb

@@ -2,7 +2,9 @@
 
 RSpec.describe RubyHToGo::FunctionDefinition do
   describe "#generate_go_content" do
-    subject { RubyHToGo::FunctionDefinition.new(definition).generate_go_content }
+    subject { RubyHToGo::FunctionDefinition.new(definition:, header_dir:).generate_go_content }
+
+    let(:header_dir) { "/path/to/include" }
 
     context "rb_define_method" do
       let(:definition) do
@@ -27,6 +29,8 @@
           // Original definition is following
           //
           //	void rb_define_method(VALUE klass, const char *mid, VALUE (*func)(ANYARGS), int arity)
+          //
+          // ref. https://github.com/ruby/ruby/blob/master/include/ruby/internal/method.h
           func RbDefineMethod(klass VALUE, mid string, arg3 unsafe.Pointer, arity int)  {
           char, clean := string2Char(mid)
           defer clean()
@@ -65,6 +69,8 @@
           // Original definition is following
           //
           //	VALUE rb_block_call(VALUE obj, ID mid, int argc, const VALUE *argv, rb_block_call_func_t proc, VALUE data2)
+          //
+          // ref. https://github.com/ruby/ruby/blob/master/include/ruby/internal/iterator.h
           func RbBlockCall(obj VALUE, mid ID, argc int, argv *VALUE, proc RbBlockCallFuncT, data2 VALUE) VALUE {
           var cArgv C.VALUE
           ret := VALUE(C.rb_block_call(C.VALUE(obj), C.ID(mid), C.int(argc), &cArgv, C.rb_block_call_func_t(proc), C.VALUE(data2)))
@@ -101,6 +107,8 @@
           // Original definition is following
           //
           //	VALUE rb_funcallv(VALUE recv, ID mid, int argc, const VALUE *argv)
+          //
+          // ref. https://github.com/ruby/ruby/blob/master/include/ruby/internal/eval.h
           func RbFuncallv(recv VALUE, mid ID, argc int, argv []VALUE) VALUE {
           ret := VALUE(C.rb_funcallv(C.VALUE(recv), C.ID(mid), C.int(argc), toCArray[VALUE, C.VALUE](argv)))
           return ret
@@ -133,6 +141,8 @@
           // Original definition is following
           //
           //	void *rb_thread_call_with_gvl(void *(*func)(void *), void *data1)
+          //
+          // ref. https://github.com/ruby/ruby/blob/master/include/rubythread.h
           func RbThreadCallWithGvl(arg1 unsafe.Pointer, data1 unsafe.Pointer) unsafe.Pointer {
           ret := unsafe.Pointer(C.rb_thread_call_with_gvl(toCPointer(arg1), toCPointer(data1)))
           return ret
@@ -165,6 +175,8 @@
           // Original definition is following
           //
           //	int rb_uv_to_utf8(char buf[6], unsigned long uv)
+          //
+          // ref. https://github.com/ruby/ruby/blob/master/include/intern/bignum.h
           func RbUvToUtf8(buf []Char, uv uint) int {
           ret := int(C.rb_uv_to_utf8(toCArray[Char, C.char](buf), C.ulong(uv)))
           return ret

_tools/ruby_h_to_go/spec/ruby_h_to_go/generator_helper_spec.rb

@@ -3,12 +3,21 @@
 RSpec.describe RubyHToGo::GeneratorHelper do
   include RubyHToGo::GeneratorHelper
 
-  describe "#go_file_name" do
-    subject { go_file_name(header_dir:, ruby_header_file:) }
+  describe "#generate_go_file_name" do
+    subject { generate_go_file_name(header_dir:, ruby_header_file:) }
 
     let(:header_dir) { "/path/to/include" }
     let(:ruby_header_file) { "/path/to/include/ruby/internal/intern/thread.h" }
 
     it { should eq "ruby_internal_intern_thread_generated.go" }
   end
+
+  describe "#generate_include_github_url" do
+    subject { generate_include_github_url(header_dir:, ruby_header_file:) }
+
+    let(:header_dir) { "/path/to/include" }
+    let(:ruby_header_file) { "/path/to/include/ruby/internal/intern/thread.h" }
+
+    it { should eq "https://github.com/ruby/ruby/blob/master/include/ruby/internal/intern/thread.h" }
+  end
 end