From 3f6c92e9d592a2b122fb2260fccee7a7dd850cb8 Mon Sep 17 00:00:00 2001
From: Jeremy Evans <code@jeremyevans.net>
Date: Sun, 19 Feb 2023 14:46:13 -0800
Subject: [PATCH] [ruby/rdoc] Omit descriptions and parameter lists for methods
 defined in C not mentioned in call-seq

This allows RDoc to better generate documentation for methods
following the Ruby core documentation guide (which omits aliases
in call-seq in most cases).  This makes documentation for methods
defined in C more similar to methods defined in Ruby.  For methods
defined in Ruby, the method description of the aliased method is
already not used (you have to explicitly document the alias to
use it).

Internally, this adds AnyMethod#has_call_seq? and #skip_description?,
and updates Darkfish to:

* only show the method name if there is a call-seq for the method,
  but the call-seq omits the method
* to omit the method description if the method is an alias or has
  aliases and has a call-seq that does not include the method

See discussion in https://github.com/ruby/ruby/pull/7316 for
details.

https://github.com/ruby/rdoc/commit/e3688de49b
---
 lib/rdoc/any_method.rb                        | 15 ++++++++
 .../generator/template/darkfish/class.rhtml   |  6 +++
 test/rdoc/test_rdoc_any_method.rb             | 38 +++++++++++++++++++
 3 files changed, 59 insertions(+)

diff --git a/lib/rdoc/any_method.rb b/lib/rdoc/any_method.rb
index 051f946a10..465c4a4fb2 100644
--- a/lib/rdoc/any_method.rb
+++ b/lib/rdoc/any_method.rb
@@ -115,6 +115,13 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     @call_seq = call_seq
   end
 
+  ##
+  # Whether the method has a call-seq.
+
+  def has_call_seq?
+    !!(@call_seq || is_alias_for&._call_seq)
+  end
+
   ##
   # Loads is_alias_for from the internal name.  Returns nil if the alias
   # cannot be found.
@@ -296,6 +303,14 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     params
   end
 
+  ##
+  # Whether to skip the method description, true for methods that have
+  # aliases with a call-seq that doesn't include the method name.
+
+  def skip_description?
+    has_call_seq? && call_seq.nil? && !!(is_alias_for || !aliases.empty?)
+  end
+
   ##
   # Sets the store for this method and its referenced code objects.
 
diff --git a/lib/rdoc/generator/template/darkfish/class.rhtml b/lib/rdoc/generator/template/darkfish/class.rhtml
index 97d175dddc..d6510336df 100644
--- a/lib/rdoc/generator/template/darkfish/class.rhtml
+++ b/lib/rdoc/generator/template/darkfish/class.rhtml
@@ -112,6 +112,10 @@
             <%- end -%>
           </div>
           <%-   end -%>
+          <%- elsif method.has_call_seq? then -%>
+          <div class="method-heading">
+            <span class="method-name"><%= h method.name %></span>
+          </div>
           <%- else -%>
           <div class="method-heading">
             <span class="method-name"><%= h method.name %></span><span
@@ -123,6 +127,7 @@
           <%- end -%>
         </div>
 
+        <%- unless method.skip_description? then -%>
         <div class="method-description">
           <%- if method.comment then -%>
           <%= method.description.strip %>
@@ -145,6 +150,7 @@
           </div>
           <%- end -%>
         </div>
+        <%- end -%>
 
         <%- unless method.aliases.empty? then -%>
         <div class="aliases">
diff --git a/test/rdoc/test_rdoc_any_method.rb b/test/rdoc/test_rdoc_any_method.rb
index 6915b466f0..b11c15420c 100644
--- a/test/rdoc/test_rdoc_any_method.rb
+++ b/test/rdoc/test_rdoc_any_method.rb
@@ -69,6 +69,20 @@ each_line(foo)
     assert_equal 'C1::m', @c1.method_list.first.full_name
   end
 
+  def test_has_call_seq?
+    m = RDoc::AnyMethod.new nil, "each_line"
+    m2 = RDoc::AnyMethod.new nil, "each"
+    assert_equal false, m.has_call_seq?
+    m.call_seq = "each_line()"
+    assert_equal true, m.has_call_seq?
+
+    m = RDoc::AnyMethod.new nil, "each_line"
+    m.is_alias_for = m2
+    assert_equal false, m.has_call_seq?
+    m2.call_seq = "each_line()"
+    assert_equal true, m.has_call_seq?
+  end
+
   def test_is_alias_for
     assert_equal @c2_b, @c2_a.is_alias_for
 
@@ -515,6 +529,30 @@ method(a, b) { |c, d| ... }
     assert_equal 'C1', @c1.method_list.last.parent_name
   end
 
+  def test_skip_description?
+    m = RDoc::AnyMethod.new nil, "each_line"
+    m2 = RDoc::AnyMethod.new nil, "each"
+    assert_equal false, m.skip_description?
+    assert_equal false, m2.skip_description?
+
+    m.is_alias_for = m2
+    m2.aliases << m
+    assert_equal false, m.skip_description?
+    assert_equal false, m2.skip_description?
+
+    m2.call_seq = "each()"
+    assert_equal true, m.skip_description?
+    assert_equal false, m2.skip_description?
+
+    m2.call_seq = "each_line()"
+    assert_equal false, m.skip_description?
+    assert_equal true, m2.skip_description?
+
+    m2.call_seq = "each()\neach_line()"
+    assert_equal false, m.skip_description?
+    assert_equal false, m2.skip_description?
+  end
+
   def test_store_equals
     loaded = Marshal.load Marshal.dump(@c1.method_list.last)