Forum: Ruby on Rails better rails source code documentation?

Bd7c1ef8f03a79860ffee163c1b8dc26?d=identicon&s=25 tsingle (Guest)
on 2013-05-22 15:49
(Received via mailing list)
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)


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?
280b78a61a968391b7e07e912be102a8?d=identicon&s=25 Robert Walker (robert4723)
on 2013-05-22 23:11
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?

http://weblog.rubyonrails.org/2012/3/7/what-is-docrails/
Please log in before posting. Registration is free and takes only a minute.
Existing account

NEW: Do you have a Google/GoogleMail, Yahoo or Facebook account? No registration required!
Log in with Google account | Log in with Yahoo account | Log in with Facebook account
No account? Register here.