Hello again Xavier! Do you have any opinion about my previous message? Do you think it's worth exploring that idea? Thanks!
On Tuesday, September 23, 2014 1:14:00 PM UTC-7, Claudio B. wrote: > > 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.
