rails/rails — pull request #17320 by claudiob (2014-10-19 15:49:32+00:00)
Title: Document overloaded button_to method with sdoc

This PR helps readers understand that `button_to` can be called with two different sets of parameters by replacing its documentation title from:

![old](https://cloud.githubusercontent.com/assets/10076/4693667/4ad55dee-57a6-11e4-9fdf-ee4999576fca.png)

to:

![new](https://cloud.githubusercontent.com/assets/10076/4693668/4adb7a08-57a6-11e4-849e-565332048ae9.png)

This PR stems from [a Google Group discussion](https://groups.google.com/forum/#!topic/rubyonrails-core/_BZXBWXuuP4) where @fxn said:

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

Rails code-base already uses `:call-seq:` in other places like [this](https://github.com/rails/rails/blob/0dfc4fa1774296ebbbf891f101e2a39225af6502/actionpack/lib/abstract_controller/callbacks.rb#L160) and [this](https://github.com/rails/rails/blob/0dfc4fa1774296ebbbf891f101e2a39225af6502/activemodel/lib/active_model/naming.rb#L127-127) and `:call-seq` is also what is used in the documentation of the Ruby language to indicate methods that can be overloaded.

[ci skip]

---

Side note on this commit: `sdoc` is being loaded from GitHub in order to include the change made by https://github.com/voloko/sdoc/pull/78 -- eventually, that change might be included in 0.4.2 and `sdoc` included from RubyGems again.