Forum: Ruby on Rails Decent documentation?

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
0a012946a32e22f4c3a5ab6866e98e45?d=identicon&s=25 Dave Smith (smitty1276)
on 2007-02-26 07:06
I know that the rails framework has "good" documentation, but I've found
it to be very shallow.  I don't know how many times I've tried to look
up a method (like the content_tag helper, for example) only to find that
it takes ":options" but has no documentation as to what those options
are.  At least, not that I can see.

Is there official documentation that I'm just missing for those :options
type arguments, and if not could someone direct me to a site that
documents them?

In this particular case, I have a div and what to use the
script.aculo.us BlindDown effect and also change the "Show" link to
"Hide".  I'm trying to find the correct format for specifying both.  All
examples (the very, very few that I can find by googling) simply use
":onclick => visual_effect(...)".. of course, that leaves no room for
anything else.
1f2eadfb41362800ebc2cf211b91d0f7?d=identicon&s=25 javier ramirez (Guest)
on 2007-02-26 10:13
(Received via mailing list)
> I know that the rails framework has "good" documentation, but I've found it to be very 
shallow.  I don't know how many times I've tried to look up a method (like the content_tag 
helper, for example) only to find that it takes ":options" but has no documentation as to 
what those options are.  At least, not that I can see.
>
Don't know where you where looking for it, but on api.rubyonrails.org
this is the explanation for "content_tag" helper.
--------
Returns an HTML block tag
<http://api.rubyonrails.com/classes/ActionView/Help...
of type name surrounding the content. Add HTML attributes by passing an
attributes hash to options. For attributes with no value like (disabled
and readonly), give it a value of true in the options hash. You can use
symbols or strings for the attribute names.
-----
it clearly says you can pass HTML attributes in the options hash. The
attributes with no values can be set by using true/false. No list of the
available options because they depend on which HTML attribute you are
working with (src makes sense for "img", but not for "a"). When there's
a list of valid options, you usually have the whole list, or you have
the reference saying "same options as...".

Also, you have some examples of options right below the explanation in
content_tag.

I'm not saying that doc is perfect, but for an API reference it's pretty
good. But.. it's only a reference, you cannot (shouldn't) expect to
learn Rails by looking at it.

My advise for that would be to have at least one good Ruby book and one
good Rails book. And I'm afraid you'd need also HTML and Javascript
background. Of course you can try without any of these, but then it's
going to be harder.

--------
Estamos de estreno... si necesitas llevar el control de tus gastos
visita http://www.gastosgem.com !!Es gratis!!
0a012946a32e22f4c3a5ab6866e98e45?d=identicon&s=25 Dave Smith (smitty1276)
on 2007-02-27 18:06
Thanks for the reply.  I think that I chose a poor example... how about
this one, file_field_tag (and most of the other methods on that page as
well)...

http://api.rubyonrails.com/classes/ActionView/Help...

It says it takes options, but it doesn't say what they are.  At the top
of the page it does say this: "NOTE: The html options disabled,
readonly, and multiple can all be treated as booleans. So specifying
:disabled => true will give disabled="disabled"."

So that would seem to imply that the html attributes can be passed as
hash values in options (I can deduce this only because i know sort of
how rails works with other helpers), but even if this assumption is
accurate the docs don't specify if those html attributes account for the
full range of options or if they are a subset of the options that are
valid.

Am I missing something else?  I'm sure that once I get it sorted out in
my head initially I will "just know" how it all works with respect to
which options do what with various helpers, but the docs seem to leave
some of it to the imagination in some places, which doesn't foster a
thorough understanding... at least that's the way it seems to me.

And I didn't mean to imply that I thought the docs were bad... The ruby
and rails docs are second only to the JDK docs in quality (in my mind)
and it is only second because Java's strong typing makes it easier to
document things clearly.

Dave


javier ramirez wrote:
>> I know that the rails framework has "good" documentation, but I've found it to be very 
shallow.  I don't know how many times I've tried to look up a method (like the content_tag 
helper, for example) only to find that it takes ":options" but has no documentation as to 
what those options are.  At least, not that I can see.
>>
> Don't know where you where looking for it, but on api.rubyonrails.org
> this is the explanation for "content_tag" helper.
> --------
> Returns an HTML block tag
> <http://api.rubyonrails.com/classes/ActionView/Help...
> of type name surrounding the content. Add HTML attributes by passing an
> attributes hash to options. For attributes with no value like (disabled
> and readonly), give it a value of true in the options hash. You can use
> symbols or strings for the attribute names.
> -----
> it clearly says you can pass HTML attributes in the options hash. The
> attributes with no values can be set by using true/false. No list of the
> available options because they depend on which HTML attribute you are
> working with (src makes sense for "img", but not for "a"). When there's
> a list of valid options, you usually have the whole list, or you have
> the reference saying "same options as...".
>
> Also, you have some examples of options right below the explanation in
> content_tag.
>
> I'm not saying that doc is perfect, but for an API reference it's pretty
> good. But.. it's only a reference, you cannot (shouldn't) expect to
> learn Rails by looking at it.
>
> My advise for that would be to have at least one good Ruby book and one
> good Rails book. And I'm afraid you'd need also HTML and Javascript
> background. Of course you can try without any of these, but then it's
> going to be harder.
>
> --------
> Estamos de estreno... si necesitas llevar el control de tus gastos
> visita http://www.gastosgem.com !!Es gratis!!
1f2eadfb41362800ebc2cf211b91d0f7?d=identicon&s=25 javier ramirez (Guest)
on 2007-02-27 18:31
(Received via mailing list)
Hi,
> this one, file_field_tag (and most of the other methods on that page as well)...
>
>
> It says it takes options, but it doesn't say what they are.  At the top of the page it 
does say this: "NOTE: The html options disabled,
> readonly, and multiple can all be treated as booleans. So specifying
> :disabled => true will give disabled="disabled"."
>
well, a bit before that line it says " Provides a number of methods for
creating form tags that doesn't rely on conventions with an object
assigned to the template like FormHelper
<http://api.rubyonrails.com/classes/ActionView/Help...
does." And in FormHelper you have the tags where it says any other
options for the input tag can be passed in the options hash, so it's
just a link away ;)
> but even if this assumption is accurate the docs don't specify if those html attributes 
account for the full range of options or if they are a subset of the options that are 
valid.
>
In my experience, when the range of options is limited it usually says
so, stating which are the valid options. When there are no descriptions
of the options it usually means the method is "agnostic" about the
options and will just delegate by letting all the options get through.
As i said, that's the general pattern I see, but for sure you could find
some exceptions and examples of underdocumented methods.
> Am I missing something else?
Well.. maybe not missing something... but maybe not using the powerful
resource of "view source" in all the API methods. If you see the source
of whatever of the methods of that page, you'll see they just call to
"tag" and pass the whole hash of options. And then if you look the doc
for "tag" you'll see it says it admits whatever you want to pass.
> And I didn't mean to imply that I thought the docs were bad... The ruby and rails docs 
are second only to the JDK docs in quality (in my mind) and it is only second because 
Java's strong typing makes it easier to document things clearly.
>
Static typing can be a good thing sometimes, I agree. Ruby's flexibility
is not free. Anyway I'd say the doc is not second to the JDK in
quality.. after all you have the links to the source code in every rails
method, and being generally short methods I'd say the source code it's
almost the best documentation you could ask for.

Anyway, I'm not trying to say ruby/rails is better/worse than java or
whatever... to each its credit and I'd say both are pretty well
documented.

But, as I said in my first e-mail.. The API doc (in any programming
language) is just a reference. You cannot try to learn only by looking
at it. I insist on my advise about getting some good
books/tutorials/documents to look for help when API is not enough.

Regards,

javier ramirez

--------
Estamos de estreno... si necesitas llevar el control de tus gastos
visita http://www.gastosgem.com !!Es gratis!!
0a012946a32e22f4c3a5ab6866e98e45?d=identicon&s=25 Dave Smith (smitty1276)
on 2007-02-27 18:41
Cool, thanks again for the reply.  I'm LOVING rails, I just have to get
used to the typing and the documentation paradigm that comes with it.

> well, a bit before that line it says " Provides a number of methods for
> creating form tags that doesn't rely on conventions with an object
> assigned to the template like FormHelper
> <http://api.rubyonrails.com/classes/ActionView/Help...
> does." And in FormHelper you have the tags where it says any other
> options for the input tag can be passed in the options hash, so it's
> just a link away ;)

Hmm... I took that to mean that it did NOT behave similarly to
FormHelper.

I think that what's getting me is the naming conventions.  Perhaps
"options" should sometimes be named "html_attributes", etc., to make the
intent clearer--at least in those cases where the options are used for
such specific purposes.  Of course there are other situations (like
"render") where "options" is clearly more appropriate.

I agree with the book thing.  I have the big 3 (the Ruby book, Ruby on
Rails, and Rails recipes)... but those don't document every nook and
cranny... they just show a couple of common use cases, for the most
part.  VERY good books, though.

In my original post I was confused because the book examples showed
things like :onclick => visual_effect(...), but I wanted to do other
things as well.  I suppose I can just do visual_effect(...) +
"other_funcs();".  I just wasn't sure if there was a more "rails" way of
doing it, and none of the examples really did anything like that.

Dave



javier ramirez wrote:
> Hi,
>> this one, file_field_tag (and most of the other methods on that page as well)...
>>
>>
>> It says it takes options, but it doesn't say what they are.  At the top of the page it 
does say this: "NOTE: The html options disabled,
>> readonly, and multiple can all be treated as booleans. So specifying
>> :disabled => true will give disabled="disabled"."
>>
> well, a bit before that line it says " Provides a number of methods for
> creating form tags that doesn't rely on conventions with an object
> assigned to the template like FormHelper
> <http://api.rubyonrails.com/classes/ActionView/Help...
> does." And in FormHelper you have the tags where it says any other
> options for the input tag can be passed in the options hash, so it's
> just a link away ;)
>> but even if this assumption is accurate the docs don't specify if those html attributes 
account for the full range of options or if they are a subset of the options that are 
valid.
>>
> In my experience, when the range of options is limited it usually says
> so, stating which are the valid options. When there are no descriptions
> of the options it usually means the method is "agnostic" about the
> options and will just delegate by letting all the options get through.
> As i said, that's the general pattern I see, but for sure you could find
> some exceptions and examples of underdocumented methods.
>> Am I missing something else?
> Well.. maybe not missing something... but maybe not using the powerful
> resource of "view source" in all the API methods. If you see the source
> of whatever of the methods of that page, you'll see they just call to
> "tag" and pass the whole hash of options. And then if you look the doc
> for "tag" you'll see it says it admits whatever you want to pass.
>> And I didn't mean to imply that I thought the docs were bad... The ruby and rails docs 
are second only to the JDK docs in quality (in my mind) and it is only second because 
Java's strong typing makes it easier to document things clearly.
>>
> Static typing can be a good thing sometimes, I agree. Ruby's flexibility
> is not free. Anyway I'd say the doc is not second to the JDK in
> quality.. after all you have the links to the source code in every rails
> method, and being generally short methods I'd say the source code it's
> almost the best documentation you could ask for.
>
> Anyway, I'm not trying to say ruby/rails is better/worse than java or
> whatever... to each its credit and I'd say both are pretty well
> documented.
>
> But, as I said in my first e-mail.. The API doc (in any programming
> language) is just a reference. You cannot try to learn only by looking
> at it. I insist on my advise about getting some good
> books/tutorials/documents to look for help when API is not enough.
>
> Regards,
>
> javier ramirez
>
> --------
> Estamos de estreno... si necesitas llevar el control de tus gastos
> visita http://www.gastosgem.com !!Es gratis!!
2ac70084b87876db2d5875341e57e283?d=identicon&s=25 David Dumaresq (Guest)
on 2007-02-27 18:52
(Received via mailing list)
To my mind, the PHP Manual has set the bar for documentation long ago.
Far
more valuable than including source snippets are the complete workable
examples for every type, function, control-structure, expression, class
and object. But it doesn't stop there, documentation and examples are
given for installation on the big three platforms, along with in-depth
discussion on security and features.

It's just so darn well organized, and it's all in one place. (I don't
even
work in PHP and I'm ranting about it. Fact is I'm jealous).
:^)

Regards,
Dave
_______________________________
Information and Educational Technology
Kwantlen University College - 604-599-2120
"So powerful is the light of unity that it can illuminate the whole
earth." --Bahá'u'lláh



javier ramirez <jramirez@aspgems.com>
Sent by: rubyonrails-talk@googlegroups.com
27/02/2007 09:28 AM
Please respond to
rubyonrails-talk@googlegroups.com


To
rubyonrails-talk@googlegroups.com
cc

Subject
[Rails] Re: Decent documentation?






Hi,
this one, file_field_tag (and most of the other methods on that page as
well)...


It says it takes options, but it doesn't say what they are.  At the top
of
the page it does say this: "NOTE: The html options disabled,
readonly, and multiple can all be treated as booleans. So specifying
:disabled => true will give disabled="disabled"."

well, a bit before that line it says " Provides a number of methods for
creating form tags that doesn?t rely on conventions with an object
assigned to the template like FormHelper does." And in FormHelper you
have
the tags where it says any other options for the input tag can be passed
in the options hash, so it's just a link away ;)

but even if this assumption is accurate the docs don't specify if those
html attributes account for the full range of options or if they are a
subset of the options that are valid.

In my experience, when the range of options is limited it usually says
so,
stating which are the valid options. When there are no descriptions of
the
options it usually means the method is "agnostic" about the options and
will just delegate by letting all the options get through. As i said,
that's the general pattern I see, but for sure you could find some
exceptions and examples of underdocumented methods.

Am I missing something else?
Well.. maybe not missing something... but maybe not using the powerful
resource of "view source" in all the API methods. If you see the source
of
whatever of the methods of that page, you'll see they just call to "tag"
and pass the whole hash of options. And then if you look the doc for
"tag"
you'll see it says it admits whatever you want to pass.

And I didn't mean to imply that I thought the docs were bad... The ruby
and rails docs are second only to the JDK docs in quality (in my mind)
and
it is only second because Java's strong typing makes it easier to
document
things clearly.

Static typing can be a good thing sometimes, I agree. Ruby's flexibility
is not free. Anyway I'd say the doc is not second to the JDK in
quality..
after all you have the links to the source code in every rails method,
and
being generally short methods I'd say the source code it's almost the
best
documentation you could ask for.

Anyway, I'm not trying to say ruby/rails is better/worse than java or
whatever... to each its credit and I'd say both are pretty well
documented.

But, as I said in my first e-mail.. The API doc (in any programming
language) is just a reference. You cannot try to learn only by looking
at
it. I insist on my advise about getting some good
books/tutorials/documents to look for help when API is not enough.

Regards,

javier ramirez

--------
Estamos de estreno... si necesitas llevar el control de tus gastos
visita
http://www.gastosgem.com !!Es gratis!!
6d3c187a8b3ef53b08e3e7e8572c4fea?d=identicon&s=25 Jeremy McAnally (Guest)
on 2007-02-27 20:18
(Received via mailing list)
Jamie (fearoffish) and I are working on improving the docs for Rails.

We're making "top-level" progress right now,
documenting/re-documenting high level things that need to be improved,
but on our lower passes, we'll drill down to this level and document
every options hash, every argument, and so on.  It'll take us a little
time to get there, but we're working on it.

If you want to watch our progress (we work all day, every Monday),
then you can check out http://fearoffish.clientsection.com/ and use
login guest and password guest.

Thanks!
Jeremy

On 2/26/07, Dave Smith <rails-mailing-list@andreas-s.net> wrote:
>
> >
>


--
http://www.jeremymcanally.com/

My free Ruby e-book:
http://www.humblelittlerubybook.com/book/

My blogs:
http://www.mrneighborly.com/
http://www.rubyinpractice.com/
0a012946a32e22f4c3a5ab6866e98e45?d=identicon&s=25 Dave Smith (smitty1276)
on 2007-02-27 20:27
Very cool.  I'll definately check it out.


Jeremy McAnally wrote:
> Jamie (fearoffish) and I are working on improving the docs for Rails.
>
> We're making "top-level" progress right now,
> documenting/re-documenting high level things that need to be improved,
> but on our lower passes, we'll drill down to this level and document
> every options hash, every argument, and so on.  It'll take us a little
> time to get there, but we're working on it.
>
> If you want to watch our progress (we work all day, every Monday),
> then you can check out http://fearoffish.clientsection.com/ and use
> login guest and password guest.
>
> Thanks!
> Jeremy
>
2ac70084b87876db2d5875341e57e283?d=identicon&s=25 David Dumaresq (Guest)
on 2007-02-28 18:35
(Received via mailing list)
This is terrific news, Jeremy! Is there any way of viewing some of your
work? I found the to-do lists on your project, but no actual content.

Regards,
Dave
_______________________________
Information and Educational Technology
Kwantlen University College - 604-599-2120
"So powerful is the light of unity that it can illuminate the whole
earth." --Bahá'u'lláh



"Jeremy McAnally" <jeremymcanally@gmail.com>
Sent by: rubyonrails-talk@googlegroups.com
27/02/2007 11:17 AM
Please respond to
rubyonrails-talk@googlegroups.com


To
rubyonrails-talk@googlegroups.com
cc

Subject
[Rails] Re: Decent documentation?







Jamie (fearoffish) and I are working on improving the docs for Rails.

We're making "top-level" progress right now,
documenting/re-documenting high level things that need to be improved,
but on our lower passes, we'll drill down to this level and document
every options hash, every argument, and so on.  It'll take us a little
time to get there, but we're working on it.

If you want to watch our progress (we work all day, every Monday),
then you can check out http://fearoffish.clientsection.com/ and use
login guest and password guest.

Thanks!
Jeremy

On 2/26/07, Dave Smith <rails-mailing-list@andreas-s.net> wrote:
>
> >
>


--
http://www.jeremymcanally.com/

My free Ruby e-book:
http://www.humblelittlerubybook.com/book/

My blogs:
http://www.mrneighborly.com/
http://www.rubyinpractice.com/
6d3c187a8b3ef53b08e3e7e8572c4fea?d=identicon&s=25 Jeremy McAnally (Guest)
on 2007-02-28 18:40
(Received via mailing list)
If you checkout the "Messages" tab, you can check out the tickets we've
submitted so far.  They're not great in number (we had a lot of setup
and
planning to do!), but we're hoping to start submitting more tickets this
week. :)

Thanks
Jeremy

On 2/28/07, David Dumaresq <David.Dumaresq@kwantlen.ca> wrote:
> "So powerful is the light of unity that it can illuminate the whole
> rubyonrails-talk@googlegroups.com  cc
> Jamie (fearoffish) and I are working on improving the docs for Rails.
>
> >
> >
> My free Ruby e-book:
> http://www.humblelittlerubybook.com/book/
>
> My blogs:
> http://www.mrneighborly.com/
> http://www.rubyinpractice.com/
>
>
>
> >
>


--
http://www.jeremymcanally.com/

My free Ruby e-book:
http://www.humblelittlerubybook.com/book/

My blogs:
http://www.mrneighborly.com/
http://www.rubyinpractice.com/
This topic is locked and can not be replied to.