Hello fantastic Rails core team!
Rails includes several methods that accept different sets of parameters.
For instance, link_to can be invoked passing the link text either as the first parameter or as a block.
While Yardoc has native support for the @overload tag to deal with these methods, RDoc does not.
Browsing through api.rubyonrails.org, I found that the way in which this is documented for Rails is
using a Signatures block, as you can see here:
The problem is that link_to is the only method that follows this convention in the entire API documentation.
My question is whether you would like to stick to this convention for the other methods that can be overloaded
and, if that’s the case, if you would accept pull requests that add the Signatures block to the documentation of
other methods that can be overloaded (for instance button_to).
I think that would make the documentation even more helpful!
We have discussed internally a little bit about it.
We’d like to document return types and possibly params types to the API. Where type has to be taken as a flexible word, as in YARD conventions: classes, modules, being able to document duck typing interfaces, several options, the possibility of being nil, etc.
But I need to find time in some imaginary dimension and propose a way to document them. In my mind this needs to be uniform/predictable, compact, and easy to read. I have some ideas, but need to test them with real source code.
So, we also think this is something to improve, and hopefully there will be a solution in the future.
I understand that finding a solution is tough using RDoc, which at most supports the cumbersome :call-seq:.
I think the best solution would to be move away from RDoc to something more “advanced”.
Yardoc is my first choice for projects, but in the case of Rails, maybe switching to TomDoc would be more feasible, since it’s
compatible with RDoc and uses a “Signature” block for overloaded methods, similar to what is happening now for link_to.
If you make any decision regarding how to move forward, I will be happy to help with the transition!
Yes, those are options, but at least personally they are not my first
Regarding tags, I don't like them for a number of reasons. In my experience
tags take a disproportionate space in the source code. Also, they tend to
promote one-liners next to params, returns, etc. I don't like one-liners
either, most of the time they add little information because there is
Not saying tags are wrong, or bad, or anything like that of course. If a
project prefers documenting with tags that is fine. Only stating why I
personally don't consider them as a first choice.
In general I don't like structured docs either, for example our guidelines
discourage the usage of labels like "Examples" and friends for method
documentation. For method APIs I like wording that speaks to a person,
intermixed with examples, with a natural flow. My model are math books,
computer science books, and Perl APIs.
So I'd like a solution similar to the one in the Ruby API (only covers
return type), something compact that stays out of the way, but it is there
if you want to look at it. If :call-seq: was not enough we could perhaps
define a new directive. Time will say.