More documentation for methods in RDoc

Problem

When I look into a source code of RDoc to debug, it's so hard to read it due to the lack of proper documentation.
For example, https://github.com/ruby/rdoc/blob/master/lib/rdoc/parser.rb#L254 has 5 parameters and I don't know what content is at all. And options is usually a Hash in other gems, but here RDoc::Options instance is expected.
While we can guess some of them, it's not ideal.

Suggestion

My proposal is to add more comments to existing source code of RDoc. This will help us read it better, understand it better and improve it better.
I'd appreciate it if current maintainers do this since they understand the structure of the code well, I could do this as well.

Misc

The documentation format will be RDoc format.

Other ideas

Or, it might be worth adding types to RDoc.

Start with lib/rdoc/parser.rb around line 254 and inspect the method parameters and existing RDoc comment style. The issue’s scope needs narrowing; completion would mean adding consistent RDoc-format comments for an agreed set of methods, with any type annotations treated as a separate decision.