Repository navigation
Prism parser no longer accepts legacy ghost method directives without a leading colon #1760
Description
Description
The previous Ruby parser accepted ghost/meta directives both with and without
an initial colon:
# method: foo
# :method: fooRDoc 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.
endWith 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 -> stringSource:
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: fooThe 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)?):/iA match can be rewritten from:
# method: footo:
# :method: fooCanonical 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
Activity
skatkov commentedon Jul 31, 2026
Should this be raised with prism parser instead?
thyresias commentedon Jul 31, 2026
No, this is an RDoc regression that arrived when switching to Prism. Prism does not handle RDoc comments.
tompng commentedon Jul 31, 2026
Sorry for the inconvience of this behavior change.
Leading-colon-less directive may unintentionally match to a normal source code comment.
For example, there are many
"# method: "comments which is not meant to be an RDoc directive.Code search: "# method:"
Since it was never documented, I'd like to keep the behavior introduced in this new major version 8.0.
thyresias commentedon Jul 31, 2026
Ok, but in that case, shouldn't there be warnings about such constructs, that used to work?
nevans commentedon Aug 26, 2026
I agree with @thyresias. It took me a while to 1) notice a bunch of documentation had disappeared, and 2) track down whether or not it was intentional.
While I understand the reason for changing the behavior, the old
RDoc::Parser::Ruby#parse_commentin rdoc 7.2 definitely seemed intentional (and I used it quite a bit). At the very least, the "Breaking Changes" section in the v8.0 release notes should be updated!nevans commentedon Aug 26, 2026
Also, haha! I only just noticed that the example in this ticket was literally documentation that I'd written. Please feel free to open broken documentation issues (or PRs) with
net-imap, too... even if it is an undocumented breaking change in rdoc. 😉 I hadn't noticed that net-imap's documentation had been broken by rdoc 8.0 until yesterday.📚️ Fix ghost `method:` directives broken by rdoc 8.0
📚️ Fix ghost `method:` directives broken by rdoc 8.0