Enhancement idea for API documentation: add signatures to overloaded methods

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: ActionView::Helpers::UrlHelper 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!

Hi Claudio,

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.

Thanks Xavier!

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

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 little space.

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.

I opened a PR at Document overloaded button_to method with sdoc by claudiob · Pull Request #17320 · rails/rails · GitHub – Thanks!