Adding YARD document support to RDoc

[okuramasafumi]

Background

I implemented a plugin system for RDoc in #1321 and YARD parsing plugin is implemented.
In the discussion with @st0012, @kou and @vinistock we decided that we should implement YARD parsing feature as a standalone feature without plugin.
The note exists in #1257 (comment)

Steps

There are some steps to have effective YARD parsing feature in RDoc.

• Adding basic framework to support YARD style document (RDoc::Yard class or similar)
• Adding support of YARD tags that already works with current RDoc such as @yield and @private
  • @yield
  • @private
• Adding support of YARD tags that needs simple modification of RDoc such @deprecated
  • Adding :deprecated directive
  • Adding @deprecated
• Adding features such as type support to utilize information from YARD
  • @return
  • @param
  • others (will be edited later)
• Adding support of YARD directives and macros
  • @!attribute
  • others (will be edited later)

I will implement these step by step.

Note

The idea of plugin system is not completely abandoned but postponed.

[kou]

@st0012 Sorry. I forgot to confirm whether YARD style tag feature should be orthogonal to markups such as RDoc format and Markdown or not.

If YARD style tag feature is orthogonal to markups, we may implement it in RDoc::Markup::PreProcess, RDoc::Parser::* or somewhere.
If YARD style tag feature is NOT orthogonal to markups, we will implement it in RDoc::{Markdown,Markup,RD,TomDoc}.

(I'm not familiar with RDoc code base yet but I feel that YARD style tag feature is orthogonal to markups. It seems that YARD also uses orthogonal approach.)

@okuramasafumi How about using check list markup for the Steps section for easy to track?

* [ ] Adding support of YARD tags that already works with current RDoc such as `@yield` and `@private`
* [ ] Adding support of YARD tags that needs simple modification of RDoc such `@deprecated`
* [ ] Adding features such as type support to utilize information from YARD
* [ ] Adding support of YARD directives and macros

[okuramasafumi]

@kou At first I thought I can use sub-issues feature, but I couldn't. So I agree, I'll converted them into a list.
And I was going to implement YARD parsing feature in RDoc::Yard class using RDoc::Markup::PreProcess just like current RDoc::TomDoc class since YARD is similar to TomDoc from RDoc perspective (another documentation format).
But if we want to add just tag support to RDoc without specifying markup: yard directive, we might want to find another approach, maybe without RDoc::Yard class.

[okuramasafumi]

@st0012 This is a friendly ping about the approach to implement YARD parsing, whether we should implement is as a standalone documentation format or as a tag support along other formats such as rdoc format. I'd love to hear opinion.

[st0012]

I'll give it a look this weekend, sorry