Update rdoc to 6.13.1

[ksss]

There are several breaking changes in RDoc.

• Interface of RDoc::Store.new has been changed.
  • Make Options a required constructor argument of Store rdoc#1309
• Return value of RDoc::Attr#comment has been changed from RDoc::Markup::Document to RDoc::Comment.
  • Stop accepting Document objects as CodeObject#comment rdoc#1210
• Interface of RDoc::{Alias,Attr,AnyMethod,MethodAttr}.new has been changed
  • Reduce unnecessary external state assignment (singleton) rdoc#1312

This PR limits rdoc to 6.13 or higher to support these breaking changes.

[tompng]

I think the test code RBS::Annotate::Formatter.translate(something.comment) should be fixed instead of accepting comment here.

def self.each_part (in line 60) can be also simplified.

       def self.each_part(doc, &block)
         if block
-          document =
-            case doc
-            when String
-              raise
-            when RDoc::Comment
-              document = doc.parse
-            when RDoc::Markup::Document
-              document = doc
-            end
+          document = doc


-  Formatter.each_part(subject.comment) do |doc|
+  raise if subject.comment.is_a?(String)
+  Formatter.each_part(subject.comment.parse) do |doc|

With some type modification

   interface _WithRDocComment
-    def comment: () -> (RDoc::Markup::Document | RDoc::Comment | String)
+    def comment: () -> (RDoc::Comment | String)
   end

   class CodeObject
-    attr_reader comment: Markup::Document | Comment | String
+    attr_reader comment: Comment | String
 
-    def comment=: (Markup::Document | Comment | String | nil) -> (Markup::Document | Comment | String)
+    def comment=: (Comment | String | nil) -> (Comment | String | nil)
    end

[ksss]

Thanks!

[st0012]

It looks like rbs uses rdoc (and ri) for 2 things:

• Locate generated ri document
• Read the comments from RDoc classes/modules/methods...etc. that's constructed by the Store instance

If that's correct, I'd recommend using Prism to write a simple visitor to index the comments. Here's a good example from Ruby LSP. Since all you need are comments, the implementation could be much simpler than it as you won't need to care about stuff like visibility...etc.

It will take some effort but will have a few benefits:

• It'll be much less likely to break as prism is built for providing these information reliably and always be up-to-date with the latest Ruby features.
  • rdoc, on the other hand, is not built to be a document source provider library as it currently is used. It's a understandable choice before prism, but now rdoc needs to focus on providing missing features. And as a result it won't be able to maintain the desired stability across most of its internal components.
• It will be easier to work with as rdoc doesn't have the best design in terms of data representation (handling both RDoc::Comment and String in multiple places is just unnecessary, which we want to fix inside RDoc too).
• It will likely be A LOT faster as you can avoid a lot of unnecessary abstractions rdoc has

[ksss]

@st0012 Thank you for reviewing.
I think using Prism is a great idea.
To reduce the dependency on RDoc, I believe we need to solve the following two issues:

• Reading comments from C source files
• Conversion to Markdown for LSP

[st0012]

Does rbs use rdoc to parse C source code? Or just uses it to retrieve the generated ri data?
AFAICT, Ruby's C source usually isn't stored locally after installation (related irb issue: ruby/irb#664).

Conversion to Markdown for LSP

I see that makes sense.

Interestingly, since ruby-lsp uses rbs to provide Ruby core's documentation, the dependency chain seems to be: ruby-lsp -> rbs -> rdoc.

[ksss]

I didn’t fully understand before.
After looking into it, it seems that RBS uses RDoc mainly in two ways, with the following process:

Writing RDoc documentation into RBS files

1. Generate ri using the RDoc CLI

   • rbs/bin/generate_docs.sh

     Line 30 in 468b036

     bundle exec --gemfile=${REPO_ROOT}/Gemfile rdoc --output=${RDOC_OUT_DIR} --root="." --all --ri --page-dir="doc" "."

2. Read the ri and convert comments into Markdown

   • rbs/lib/rbs/annotate/formatter.rb

     Line 86 in 468b036

     formatter = RDoc::Markup::ToMarkdown.new

3. Write the Markdown comments into RBS files

   • rbs/lib/rbs/annotate/rdoc_annotator.rb

     Line 24 in 468b036

     Writer.new(out: io).preserve!(preserve: preserve).write(decls)

Reading RBS file comments as RDoc documentation

1. Use an RDoc plugin

   • rbs/lib/rdoc/discover.rb

     Line 11 in 468b036

     ::RBS::RDocPlugin::Parser.new(@top_level, @content).scan

2. Parse the RBS file

   • rbs/lib/rdoc_plugin/parser.rb

     Line 17 in 468b036

     _, _, decls = ::RBS::Parser.parse_signature(@content)

3. Read comments in the RBS file as RDoc documentation
   • https://github.com/ruby/rbs/blob/master/lib/rdoc_plugin/parser.rb

We can try it with:
$ bundle exec rdoc core/array.rbs

[st0012]

@ksss Thank you for the summary, this is very helpful 🙏

I wonder if we should move the plugin into rdoc and become its own parser. It'll make rdoc and rbs less coupled as rdoc can simply disable that parser when rbs gem is not installed. This should reduce the chance of rdoc breaking rbs. WDYT?

[ksss]

@st0012 I think it is a very excellent idea!

@soutaro How about it?

[soutaro]

@st0012 Hi Stan!

Moving the plugin to rdoc gem would make sense. (But it may result breaking rdoc, when RBS is updated...)

We have rbs annotate command that also uses RDoc, and I don't think this feature cannot be easily moved to rdoc. It means rbs gem will continue depending on rdoc internal (and break again easily.)

So, we should focus if it would benefit the end users, and because the rdoc plugin has a little (maybe zero?) users, the conclusion doesn't looks obvious to me.

[soutaro]

Merge this for now.
We can consider if we can move some parts to RDoc later.

[st0012]

Yeah let's get it merged first and perhaps talk a bit more about future integration during RubyKaigi 😄

[ksss]

👍