tsingle wrote in post #1109831:
I'm new to both ruby and rails, coming from lots of experience with other languages and frameworks, and I'm struck by how poor the rails source code documentation is. For example, I'm looking at activerecord-3.2.13/lib/active_record/connection_adapters/abstract/quoting.rb, which contains
# Quotes the column value to help prevent # {SQL injection attacks}[http://en.wikipedia.org/wiki/SQL_injection\]. def quote(value, column = nil)
First of all this method is part of the connection adapters. I'm quite sure it was never intended to be used by developers at the application layer. It should be considered a private implementation detail that could get you into trouble if used directly. This method could also easily be overridden by database specific connection adapters. The MySQL version may differ from the PostgreSQL version for example. Using this abstract version could possibly cause you future pain.
I would consider pretty much anything in connection_adapters as private implementations unless you are creating your own database adaptor. I tend to doubt that you are.
I understand that it's debatable whether or not an end-user should directly use this, but my googling finds that many end users do in fact use it ...
I wouldn't consider it "debatable" myself. I would consider it a private and intentionally undocumented method. If you choose to use it, then use it at your own risk.
If you really want to know more about methods like these, there is the "Source: show" link right there in the docs. Sometimes the best documentation is the code itself.
How should I go about finding the answer to questions like "What is the 'column' argument? When might I want to use it?". I.e., I hoped the comments near the method definition would help ... is there a Ruby Way to answer these kinds of questions?
Assuming my complaint about the lack of documentation is legitimate, what's being done to correct it? How can I help?