Skip to content

Use inherited documentation when checking alias parameter coverage - #1780

Open
sjh9714 wants to merge 1 commit into
ruby:masterfrom
sjh9714:codex/20260818-1567-alias-param-coverage
Open

Use inherited documentation when checking alias parameter coverage#1780
sjh9714 wants to merge 1 commit into
ruby:masterfrom
sjh9714:codex/20260818-1567-alias-param-coverage

Conversation

@sjh9714

@sjh9714 sjh9714 commented Aug 18, 2026

Copy link
Copy Markdown
Contributor

Summary

Fixes #1567.

rdoc -C1 lists the parameters of an aliased method as undocumented, even
though the alias inherits the original method's documentation. rdoc -C on the
same file already reports it as fully covered.

Given the file from the issue:

##
# Instance methods

module InstanceMethods
  ##
  # Takes a +value+ or a +block+ and returns a value monad.

  def _ value = nil, &block
    # ...
  end

  alias value  _
  alias expect _
end

rdoc -C1 reports:

The following items are not documented:
  Method:
    InstanceMethods#expect
      Undocumented params: value, block
    InstanceMethods#value
      Undocumented params: value, block

Methods:     3 (0 undocumented)
Parameters:  6 (4 undocumented)

Methods: 3 (0 undocumented) is the tell: the aliases already count as
documented, but their parameters do not.

RDoc::MethodAttr#documented? resolves inherited documentation through
#is_alias_for and #see, while RDoc::Stats#undoc_params parses
method.comment directly, which is empty for an alias, so every parameter comes
back undocumented.

Changes

  • RDoc::Stats#undoc_params falls back to the comment of #is_alias_for or
    #see when the method carries no comment of its own. A method with its own
    comment is unaffected, so the only behavior change is for objects
    #documented? already treats as documented.
  • Regression test alongside the existing test_undoc_params_* cases.

Testing

  • ruby -Ilib -Itest test/rdoc/rdoc_stats_test.rb -n /undoc_params/ — the new
    test fails without the fix (<["a"]> was expected to be empty) and passes
    with it.
  • rake normal_test — 2520 tests, 6165 assertions, 0 failures, 0 errors.
  • bundle exec rubocop lib/rdoc/stats.rb test/rdoc/rdoc_stats_test.rb — no
    offenses.
  • ruby -Ilib exe/rdoc -C1 --op /tmp/rdocout /tmp/rdoc_bug.rb on the file above
    now reports Parameters: 6 (0 undocumented) and 100.00% documented.

An alias has no comment of its own, so RDoc::Stats#undoc_params reported
every parameter of an aliased method as undocumented even though
RDoc::MethodAttr#documented? already resolves the inherited documentation.
Fall back to the comment of #is_alias_for or #see when the method has none.
@sjh9714
sjh9714 requested a deployment to fork-preview-protection August 18, 2026 01:17 — with GitHub Actions Waiting
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

rdoc -C1 reports alias method arguments as uncovered

1 participant