Hello Xavier!
I understand your point. I looked at the Ruby API doc, and they extensively
use :call-seq:.
I gave it a try and added the following lines to the doc preamble of
button_to:
# :call-seq:
# button_to(name = nil, options = nil, html_options = nil)<br />
# button_to(options = nil, html_options = nil, &block)
and this is the result:
<https://lh4.googleusercontent.com/-9b9kHzdH-7A/VCHUORTZP1I/AAAAAAAAATc/2J8xG6PiFcU/s1600/sdoc.png>
I would say that it does not look bad and it's quite informative. What do
you think?
On Tuesday, September 23, 2014 12:06:37 PM UTC-7, Xavier Noria wrote:
>
> 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.
>
>
--
You received this message because you are subscribed to the Google Groups "Ruby
on Rails: Core" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to rubyonrails-core+unsubscr...@googlegroups.com.
To post to this group, send email to rubyonrails-core@googlegroups.com.
Visit this group at http://groups.google.com/group/rubyonrails-core.
For more options, visit https://groups.google.com/d/optout.
