Better rails source code documentation?

Rails
1

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}[SQL injection - Wikipedia].
def quote(value, column = nil)

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
…

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?

2

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}[SQL injection - Wikipedia].
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?