Here’s an example of some atrocious Rails API documentation.
(I say “of the week” which raised the question whether I could really find an atrocious Rails doc every week . . . but I probably can.)
Here’s the doc for the link_to helper:
http://api.rubyonrails.org/classes/ActionView/Helpers/UrlHelper.html#M001378
Notice that there is a heading “Options” describing keys such as :confirm, :popup, etc.
Well guess what? Those Options are for the second Hash, i.e., html_options. How a newbie would ever figure this out is beyond me. I suppose you’re supposed to follow the link over to url_for and figure out that those options are for the first Hash . . . and then somehow that the “Options” given for link_to are for the 2nd Hash. One of my students in my Harvard Ruby/Rails course stumbled across this.
