Prism parser no longer accepts legacy ghost method directives without a leading colon
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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