Rails Document must be more detailed otherwise


#1

In java/c++ the method signature provide a good details on which
parameters
the method accept, but in rails the ability to send hash as parameters
make
it impossible
to know which parameters can be send.

This ability make the rails API doc a must to be full of details and not
supply partial examples of usage.

When for example I see link_to_remote(name, options = {}, html_options

{})
I would like to know exactly the keys which I can send for “options”
hash
parameter and not start figured it out by examples.

Any way, where can I find a good rails API other then
http://api.rubyonrails.com/ without missing details which cover the full
parameters for each method.(If exist)

Sharon


#2

Right now, the best source of information is Agile Web D. with
Rails, by Thomas Heinemeier H., the inventor of Rails.

sharon lin wrote:

In java/c++ the method signature provide a good details on which
parameters
the method accept, but in rails the ability to send hash as parameters
make
it impossible
to know which parameters can be send.

This ability make the rails API doc a must to be full of details and not
supply partial examples of usage.

When for example I see link_to_remote(name, options = {}, html_options

{})
I would like to know exactly the keys which I can send for “options”
hash
parameter and not start figured it out by examples.

Any way, where can I find a good rails API other then
http://api.rubyonrails.com/ without missing details which cover the full
parameters for each method.(If exist)

Sharon


#3

Mick S. wrote:

Right now, the best source of information is Agile Web D. with
Rails, by Thomas Heinemeier H., the inventor of Rails.

Umm… either you’re joking (in which case, stoopid me), or you mean
Dave T., and David Heinemeier H. (only one of which is the
inventor of Rails :slight_smile:

Alan


#4

The Agile book is fanastic for learning Rails, but it doesn’t give a
full API reference.

The reference on api.rubyonrails.com does seem to be fairly vague with
this kind of detail…

Anyone know if there is a more extensive API reference available or on
the way?

Steve


#5

Oh Dear! I really shouldn’t try to post anything when I’ve just got up
:o

I’l get another cup of coffee :smiley:

Alan F. wrote:

Mick S. wrote:

Right now, the best source of information is Agile Web D. with
Rails, by Thomas Heinemeier H., the inventor of Rails.

Umm… either you’re joking (in which case, stoopid me), or you mean
Dave T., and David Heinemeier H. (only one of which is the
inventor of Rails :slight_smile:

Alan


#6

Stephen B. wrote:

The Agile book is fanastic for learning Rails, but it doesn’t give a
full API reference.

The reference on api.rubyonrails.com does seem to be fairly vague with
this kind of detail…
I generally find that it’s worth digging into the source for this sort
of thing. Apart from finding out available options, I find I actually
learn a lot about how the whole thing fits together that way…


Alex


#7

Can you give examples of the vagueness. I have found the api docs to
be the best source of information (and a good source at that), of how
Rails actually works.


#8

Andrew G.berg wrote:

Can you give examples of the vagueness. I have found the api docs to
be the best source of information (and a good source at that), of how
Rails actually works.

So have I. Using the api and this forum i havnt yet come across a
problem i couldnt quickly resolve.


#9

there’s also http://railsmanual.org

which has plenty of annotations to the API, mostly the older stuff, so
not yet anything for form_remote_tag. It’s a great idea though, i hope
it’s not stalled and continues to be updated.


#10

The problem is that you need to know the terms that are used in the API.
You’ll get used to it, but it takes some time.

   Erik.

Chris R. schreef:


#11

Andrew G.berg wrote:

Can you give examples of the vagueness.
Yes, I can?

What does the block that you can pass to
ActionView::Helpers::FormTagHelper#form_tag() do, and why does it exist?

What are the possible valid options to
ActionView::Helpers::ScriptaculousHelper#sortable_element(), should the
keys be strings or symbols, and how do you represent booleans?

If you merge() two HashWithIndifferentAccesses, one with a string key
and the other with a symbol key that HWIA treats as the same, which
value gets kept?

Where is routing documented?

When you assert_routing, what format should the expected options hash
take, and how should you express ‘*foo’ route elements? What does the
extras hash do?

I’m not asking these questions because I want to know the answers, I’m
just pointing out some of the holes in the docs at api.rubyonrails.com
I’ve run into that have had me digging into the source. I’m not
pointing them out to denigrate the Rails-core team in any way, but if I
didn’t have access to the source, I certainly couldn’t answer these
questions (and others like them) without jumping through a lot of hoops.

I have found the api docs to
be the best source of information (and a good source at that), of how
Rails actually works.
It’s good, but it’s not great. If I was much of a documentation writer,
I’d feel a little more confident about knocking up some doc-patches, but
I’ve got no idea if a) I’d have time to do it well, or b) I could do
them well enough for them to be accepted.