Prism parser no longer accepts legacy ghost method directives without a leading colon
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 76/100
- Issue type
- Bug
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- ruby
- Domain
- documentation
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.
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
- Dominant language
- Ruby
- Stars
- 930
- Forks
- 472
- Avg merge
- 2d 8h
- Merged PRs (30d)
- 12
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing 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.
More from ruby/rdoc
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
RDoc 8.0.0 gem omits `doc/rdoc/example.rb`, which is referenced by the packaged markup documentationPossibly taken @OskarEichler claimed this 80 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
Maintainers usually reply within 1 day
-
markdown html excerpt includes link partsPossibly taken @anyingiit claimed this 26 days ago. Open
Difficulty 3/5 1-2 days Newbie friendliness 66/100
Maintainers usually reply within 1 day
-
Regexp generated from unescaped input in #expand_classPossibly taken @jaynetics claimed this 39 days ago. Open
Difficulty 1/5 Under an hour Newbie friendliness 25/100
Maintainers usually reply within 1 day
Similar issues
-
needs verification
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
Maintainers usually reply within 13 days
-
🐛 bug 👩💻 équipe CE 🧑🏭 entreprises
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
betagouv/conseillers-entreprises#4808 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
yosiat/panko_serializer#250 ·