@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

@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.

@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.

I'll give it a look this weekend, sorry

I'd like to give my perspective on this one. I see YARD comments falling into two categories: directives (or "attributes") and type annotations.

Directives

These are all of the things that are not related to types, like @deprecated or @private. I'm 100% in favour of adding these because standardizing these directives as part of RDoc gives guarantees to the entire tooling ecosystem - allowing all tools to build richer functionality on top.

For example, the Ruby LSP will be able to index that information and then we can show that a method is deprecated or private in the editor. We can also allow go to definition if the new substitute method is link to. Something like this

class Foo
  # @deprecated because of a, b and c. Use {Foo#baz} instead
  #                                         ^ going to definition here can take you to baz
  def bar; end

  def baz; end
end

Type annotations

For the @param, @return and all other type annotations, I'm not so convinced that we should standardize on the approach YARD took. All static analysis tooling in the Ruby ecosystem seem to be moving towards RBS in comments for types. Anecdotally, we have received great feedback so far about the RBS support for Sorbet.

So I wonder if we shouldn't instead standardize that type annotations must be made using RBS. While I understand that a lot of projects are already annotated with YARD, making this move towards standardizing the type annotations will help the entire tooling ecosystem to have guarantees about indexing type information. They can all speak a single language - the frontend of annotations is the same.

So I would vote that RDoc should lead the way and standardize like this:

class Foo
  # @deprecated because of a, b and c. Use {Foo#baz} instead
  #: (Integer) -> String
  def foo(a); end

  #: (Integer, String) -> String
  def baz(a, b); end

  # @private
  #: -> void
  def bar; end
end

Finally, if people agree with this direction, then I think all markups should support these features.

@soutaro Do you have any opinion for the type annotation parts in #1344 (comment) ?