ruby / ruby/rdoc

Prism parser no longer accepts legacy ghost method directives without a leading colon

Open
#1,760 6 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Ruby
Stars
930
Forks
465
Avg merge
3d 10h
Merged PRs (30d)
27

Description

Description

The previous Ruby parser accepted ghost/meta directives both with and without
an initial colon:

# method: foo
# :method: foo

RDoc 8.0.0 only recognizes the canonical second form.

Although the form without the initial colon is not the currently documented
syntax, the previous parser explicitly supported it. Existing documentation
relies on this behavior.

Minimal reproduction
class Example
  ##
  # method: legacy_method
  # A legacy ghost method directive.

  ##
  # :method: canonical_method
  # A canonical ghost method directive.
end

With RDoc 6.17.0:

Example.method_list.map(&:name)
# => ["legacy_method", "canonical_method"]

With RDoc 8.0.0:

Example.method_list.map(&:name)
# => ["canonical_method"]

The previous parser deliberately made the initial colon optional:

/^# +:?method:/

It did the same for singleton-method and attribute directives.

Real-world example

net-imap documents members created dynamically by Struct using this
syntax:

##
# method: media_type
# :call-seq: media_type -> string

Source:

https://github.com/ruby/net-imap/blob/v0.6.4.1/lib/net/imap/response_data.rb#L903

RDoc 8 does not create the ghost method, so references such as:

rdoc-ref:BodyTypeBasic#media_type

cannot be resolved.

Expected behavior

For backward compatibility, the Prism parser should recognize both:

# method: foo
# :method: foo

The same compatibility should apply to:

method
singleton-method
attr
attr_reader
attr_writer
attr_accessor
Suggested fix

Before passing Ruby comments to the common directive parser, normalize legacy
meta directives to their canonical form.

For example:

LEGACY_META_DIRECTIVE =
  /^([ \t]*\#[ \t]+)(singleton-method|method|attr(?:_reader|_writer|_accessor)?):/i

A match can be rewritten from:

# method: foo

to:

# :method: foo

Canonical directives must remain unchanged.

Tests should cover both forms for methods, singleton methods, and attributes.

Environment
Ruby 4.0.5 +PRISM
RDoc 8.0.0
Prism 1.9.0

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the Prism parser's comment handling and trace how comments reach the common directive parser. Add tests covering legacy and canonical method, singleton-method, and attribute directives, then verify both forms produce the expected members and preserve canonical directives.

Written by the indexing model from the issue text.

Assessment

Tech stack
ruby
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.