How to read rails documentation


#1

One of the criticism I have heard about rails is that the documentation
is
bad. I must admit I have a hard time trying to follow it and I wonder
if
anyone can shed some light on it for me. For example, I am looking at
the
schema.rb file generated and I noticed this line:

create_table “accounts”, :force => true do |t|

I thought to myself, what does :force => true mean? So I went to the
docs
to look it up. I figured this is the best place to start:

http://rubyonrails.org/api/classes/ActiveRecord/Schema.html

On the page, no mention of the create_table method (is it a method?).
For
those of us used to looking at JavaDocs, even if a method is inheirited
from
a parent object, the doc shows you that, and gives you a link right to
the
parent object where is it define. But ok, fine, I’ll check the parent:

http://rubyonrails.org/api/classes/ActiveRecord/Migration.html

create_table is not listed under the methods. Is create_table not a
method? It is listed under “Available transformations”. What is a
transformation? Anyway, here is what it has:

create_table(name, options) - Creates a table called name and makes the
table object available to a block that can then add columns to it,
following
the same format as add_column. See example above. The options hash is
for
fragments like “DEFAULT CHARSET=UTF-8” that are appended to the create
table
definition.

Ok, so what are the available options, and how do I find out what they
do?

From looking at my schema.rb, force appears to be a valid boolean option,
but I have no way of knowing what effect it has. I’m actually not that
concerned about what effect force has, but more so just understanding
how
I’m supposed to read & understand the docs. I feel like as I work with
rails this kind of thing comes up all the time. There is some magic
method
that takes a hash of arguments and it is near impossible to trace down
what
the vaild options are.


#2

On 4/4/06, Paul B. removed_email_address@domain.invalid wrote:

Ok, so what are the available options, and how do I find out what they do?
From looking at my schema.rb, force appears to be a valid boolean option,
but I have no way of knowing what effect it has. I’m actually not that
concerned about what effect force has, but more so just understanding how
I’m supposed to read & understand the docs. I feel like as I work with
rails this kind of thing comes up all the time. There is some magic method
that takes a hash of arguments and it is near impossible to trace down what
the vaild options are.

Start here: http://api.rubyonrails.org/

On the left, under Methods, click on “create_table.” All of the
options are explained.

– James


#3

wow, that’s easy enough. Now how about the scripts, like
script/generate
scaffold, how do I find out the details for that?


#4

2006/4/4, Paul B. removed_email_address@domain.invalid:

wow, that’s easy enough. Now how about the scripts, like script/generate
scaffold, how do I find out the details for that?

script/generate --help
script/generate scaffold --help

Bye !


#5

nice, thanks