rails/rails — pull request #6697 by dpassage (2012-06-10 22:12:55+00:00)
Title: Documentation for where method on relations

https://groups.google.com/d/topic/rubyonrails-core/IquCr3-vNVE/discussion generated some good discussion, but also some plain noise because the "where" method in Active Record isn't documented.

I decided to fix that. This commit adds rdoc for #where, based on both the Rails Guide and a perusal of the Active Record test suite. I'm opening a pull request, rather than just committing to docrails, because I want some input on style and substance for documenting this important method.

I also found examples in the test suite of condition templates like this:

User.where("field = '%s'", "value")

I don't see this printf-style mentioned anywhere in the guides or other external documentation; I'm wondering if it's still valid/considered in good taste. If it is, then I'd appreciate a pointer to which %-escapes are supported.