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

[thyresias]

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

[skatkov]

Should this be raised with prism parser instead?

[thyresias]

Should this be raised with prism parser instead?

No, this is an RDoc regression that arrived when switching to Prism. Prism does not handle RDoc comments.

[tompng]

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:"

# method: description of method parameter named `method` (e.g. :put or :post)

# Long line that describes about some
# method:
#   p some() #=> :some

Since it was never documented, I'd like to keep the behavior introduced in this new major version 8.0.

[thyresias]

Ok, but in that case, shouldn't there be warnings about such constructs, that used to work?