More documentation for methods in RDoc

[okuramasafumi]

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.