rdoc-markdown 0.22.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f862496849b46537b75b6d25d1e313a830a9aaf535854a5233fad42081b0a0c
-  data.tar.gz: e7505ea0dadde9f2f6d357d96ce022e9b9cdc3b0a5457a1648a49bffb4c09fd4
+  metadata.gz: c3c8efb1f673d2b95ce85319abcf5e35b8cd46d3fa31260dbf2c4082d952556e
+  data.tar.gz: da6d4d6a45e85c905c087065ab6ddd235097c75962fd2ee701d576e4f9d44070
 SHA512:
-  metadata.gz: d6fb9ba4435a1b7e3ae3d9da59b2102a47574dc8c33570ca807358bec137116b17474a1721277d3ebe5833e1093b016fcc08a1dfd24d93f71f12b785382259ca
-  data.tar.gz: 3f25a645ec86e266b05fc0b934e2aa82f088011a6bf9906b881c796eff4c86684fafe05da70259fbdeb0c0221a2bfaf28262a867a292d58add5f1b4ca329bf5a
+  metadata.gz: 1914a8ec4a9a6bdc749f997eb6ac39bd418333aeabe12102f6933c95a3909961ec3a1aa8e54c7fbb0315cb4d7f76ec2eb70f5bef452dc547f0dc6ba2fd4b725c
+  data.tar.gz: 8db50c4acd4fce77dd8c3b52516fe2db549acbdb18481bb8caa3c2ee94091caed11236d99898aaa7f19b9c4813a6a48a1839bd86abc6a370a767f4c96fb76d0b

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.23.0
+
+- Show optional argument defaults in method headings.
+- Preserve Ruby expressions in optional argument defaults.
+
 ## 0.22.0
 
 - BREAKING: Use Ruby notation in search-index names: `Duck.MAX_VELOCITY` becomes `Duck::MAX_VELOCITY`, and instance attributes use `Class#attr` instead of `Class.attr`. Consumers matching index names must update these lookups. Class-level attributes retain `Class.attr`; document paths and anchors are unchanged.

data/lib/rdoc/generator/markdown/signatures.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "prism"
+
 # Normalizes RDoc and RBS method signatures for headings.
 module RDoc::Generator::Markdown::Signatures
   # Signature opening delimiters and their matching closers.
@@ -15,18 +17,17 @@ module RDoc::Generator::Markdown::Signatures
   # @return [String] Complete signature including the method name or documented receiver.
   def self.render_method_signature(method, store)
     name = method.name
-    signatures = method.type_signature_lines || store.rbs_signature_for(method)
-    if !signatures && ["[]", "[]="].include?(name) && (call_seq = method.call_seq)
+    type_signatures = method.type_signature_lines || store.rbs_signature_for(method)
+    if !type_signatures && ["[]", "[]="].include?(name) && (call_seq = method.call_seq)
       return call_seq.lines.map { |line| normalize_signature(line) }.join(" | ")
     end
-    signatures ||= [method.param_seq]
+    params = method.params
 
-    signatures = signatures.filter_map do |signature|
+    signatures = (type_signatures || [method.param_seq]).filter_map do |signature|
       next unless signature&.match?(/\S/)
 
-      signature = normalize_signature(signature)
-      signature = " #{signature}" if signature.start_with?("->")
-      merge_method_signature_arguments(signature, method.params)
+      signature = merge_method_signature_arguments(signature, params)
+      type_signatures ? signature : restore_method_parameter_defaults(signature, params)
     end
 
     "#{name}#{signatures.empty? ? "()" : signatures.join(" | ")}"
@@ -41,13 +42,43 @@ module RDoc::Generator::Markdown::Signatures
     signature.gsub("->", " -> ").gsub(/\s+/, " ").strip
   end
 
-  # Merges RDoc parameter names into a type-only signature.
+  # Restores source defaults for bare argument names in an untyped call sequence.
+  #
+  # @param signature [String] Normalized call sequence without the method name.
+  # @param raw_params [String, nil] Method parameter list from RDoc.
+  # @return [String] Signature with matching source default expressions preserved.
+  def self.restore_method_parameter_defaults(signature, raw_params)
+    signature_args, signature_suffix = split_signature_arguments_and_suffix(signature)
+    source_params = ruby_parameters(raw_params)
+    documented_params = ruby_parameters(signature_args)
+    return signature unless source_params && documented_params
+
+    defaults = source_params.optionals.to_h { |param| [param.name.to_s, param.slice] }
+    signature_parts = documented_params.compact_child_nodes.map(&:slice)
+    default_parts = signature_parts.map { |part| defaults.fetch(part, part) }
+    return signature if default_parts == signature_parts
+
+    "(#{default_parts.join(", ")})#{signature_suffix}"
+  end
+
+  # Parses Ruby parameter boundaries without evaluating or rewriting default expressions.
+  #
+  # @param params [String, nil] Parenthesized or bare Ruby parameters.
+  # @return [Prism::ParametersNode, nil] Parameters, or nil for empty or invalid syntax.
+  def self.ruby_parameters(params)
+    result = Prism.parse("def _ #{params.to_s.lstrip}\nend")
+    result.value.statements.body.first.parameters if result.success?
+  end
+
+  # Normalizes a signature and merges RDoc parameter names into type-only arguments.
   #
   # @param signature [String] Method signature from RDoc call sequence.
   # @param raw_params [String, nil] Method parameter list from RDoc.
   #
   # @return [String] Signature with names added when safe.
   def self.merge_method_signature_arguments(signature, raw_params)
+    signature = normalize_signature(signature)
+    signature = " #{signature}" if signature.start_with?("->")
     params = raw_params.to_s.strip
     params = params[1...-1] if params.start_with?("(") && params.end_with?(")")
 
@@ -106,25 +137,20 @@ module RDoc::Generator::Markdown::Signatures
   # @return [Array<String>] Signature parts.
   def self.split_signature_list(list)
     parts = []
-    current = +""
+    start = 0
     delimiters = []
 
-    list.each_char do |char|
+    list.each_char.with_index do |char, index|
       if char == "," && delimiters.empty?
-        parts << current.strip
-        current.clear
-      else
-        closing = DELIMITER_PAIRS[char]
-        if closing
-          delimiters << closing
-        elsif char == delimiters.last
-          delimiters.pop
-        end
-        current << char
+        parts << list[start...index].strip
+        start = index + 1
       end
+      closing = DELIMITER_PAIRS[char]
+      delimiters << closing if closing
+      delimiters.pop if char == delimiters.last
     end
 
-    parts << current.strip unless current.empty?
+    parts << list[start..].strip if start < list.length
     parts
   end
 end

data/lib/rdoc/markdown/version.rb

@@ -5,6 +5,6 @@ module Rdoc
   # @private
   module Markdown
     # @private
-    VERSION = "0.22.0"
+    VERSION = "0.23.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rdoc-markdown
 version: !ruby/object:Gem::Version
-  version: 0.22.0
+  version: 0.23.0
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov