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.
