How to Read Ruby API / Documentation

[Chinna Karuppan]

Hi,
I have some background in java.and the api is nicely defined...in terms
of what is public,protected and private.I was trying to use the
define_method in one of my class and it would not work because it is
private(but that is not point here.the point how to know which all
methods are for public use and which is protected and which is
private--> not for consumers of the library)...can some body tell as to
how to read the api ( I am using http://www.ruby-doc.org/core/) or am I
missing something???
THnks
CHinna

 

[Chinna Karuppan]

I know there are methods like private_methods, protected_methods,
instance_methods.I don't want to everytime call these methods...
Also How do I know which is a instance method/ class method....don't
tell me :: is the class method and #/. is the instance method.Why does
it not show properly on the API...
THnks

 

[7stud --]

You will have to get used to the fact that the Ruby docs are horrible.

 

[James Britt]

You will have to get used to the fact that the Ruby docs are horrible.

Patches welcome.

 

[Gregory Seidman]

You will have to get used to the fact that the Ruby docs are horrible.

The *free* Ruby docs leave something to be desired. The Pickaxe book is
pretty good in a lot of ways, and I've also gotten a lot of value out of
the O'Reilly Ruby Pocket Reference I won at RubyConf.

Beyond that, Foo.instance_methods.grep(/bar/) is your friend. Playing
around in irb is invaluable. I even look things up in ri occasionally. The
wealth of expertise available on this mailing list and on #ruby-lang on
freenode.net have also helped me a great deal. And Google is always your
friend.

Complaining that the free documentation for the free (and Free)
language/platform you're using leaves something to be desired is absurd.
Feel free to contribute better documentation if you think it's a good use
of your time. (Saying it's worth someone else's time but not your own is
the height of hypocrisy unless you're willing to pay money for that other
person's time.) Otherwise, use the other resources available to you.

--Greg

 

[7stud --]

Patches welcome.

Open up the docs to user comments, and then they will be self
documenting. See the php model.

 

[Phillip Gawlowski]

Open up the docs to user comments, and then they will be self
documenting. See the php model.

Then host them yourself, and allow user comments.

- Phillip

 

[James Britt]

Open up the docs to user comments, and then they will be self
documenting. See the php model.

Is that what stops you from contributing to the docs? Or would you
prefer that others make the contributions, while you simply declare them
to be horrible?

There are some people who have taken the time to create and/or improve
the docs. You can bitch about their efforts, but a tangible
contribution would be so much more durable.


(I apologize if you have been sending in doc patches.)

ruby-doc.org is currently running with Nitro; I'm inclined to port it to
Ramaze.

If anyone is interested in helping me assemble a Ramaze-based means of
allowing doc comments, with decent spam blocking, drop me a line. (I
prefer to use Og or Sequel for the ORM, but open to informed suggestions
otherwise.)

Note that the API doc content would still need to be auto-generated from
the svn ruby source and doing so should not interfere with any existing
comments.


--
James Britt

"In physics the truth is rarely perfectly clear, and that is certainly
universally the case in human affairs. Hence, what is not surrounded by
uncertainty cannot be the truth."
- R. Feynman

 

[Chinna Karuppan]

I know that a lot of effort is being put by volunteers and appreciate
it.But as for a nuby do you think there is a place I can go to check
which is the list of protected methods , private methods....and probably
other method that I get from its super classes.I use the nobkitt as
well to check the public methods....Am I missing some thing.
Once again Thnks for you efforts.
THnks
Chinna

 

[Jeremy McAnally]

I agree with you.

I'm not sure why people want to learn Ruby in a vacuum or something.
"These docs don't teach me every possible behavior of method (x)!!!!
THESE SUCK!!!!" Get your hands dirty in irb, otherwise you won't
really *learn* how to use it right, IMHO.

Ruby documentation needs help (no I haven't submitted patches to Ruby
but I have submitted a lot to Rails), but hopefully some things that
are being worked on will bring up the ease of doc edits, the quality
of generated documentation, and the quality of documentation content.
We shall see though.

--Jeremy

The *free* Ruby docs leave something to be desired. The Pickaxe book is
pretty good in a lot of ways, and I've also gotten a lot of value out of
the O'Reilly Ruby Pocket Reference I won at RubyConf.

Beyond that, Foo.instance_methods.grep(/bar/) is your friend. Playing
around in irb is invaluable. I even look things up in ri occasionally. The
wealth of expertise available on this mailing list and on #ruby-lang on
freenode.net have also helped me a great deal. And Google is always your
friend.

Complaining that the free documentation for the free (and Free)
language/platform you're using leaves something to be desired is absurd.
Feel free to contribute better documentation if you think it's a good use
of your time. (Saying it's worth someone else's time but not your own is
the height of hypocrisy unless you're willing to pay money for that other
person's time.) Otherwise, use the other resources available to you.

--Greg

--
http://jeremymcanally.com/
http://entp.com

Read my books:
Ruby in Practice (http://manning.com/mcanally/)
My free Ruby e-book (http://humblelittlerubybook.com/)

Or, my blogs:
http://mrneighborly.com
http://rubyinpractice.com

 

[Gilbert Rebhan]

I'm not sure why people want to learn Ruby in a vacuum or something.
"These docs don't teach me every possible behavior of method (x)!!!!
THESE SUCK!!!!" Get your hands dirty in irb, otherwise you won't
really *learn* how to use it right, IMHO.

+1
learning by doing, as for other languages too
hard work after all for the zapping generation
I know other communities and the ruby community is

premium/super/excellent !!

Every language documentation misses / lacks something.
But from what i know especially the ruby community is
VERY newbie friendly and gets you easily over the first hurdles.
There are so many blogs, tutorials and docs around ...

And when you're @ high level some sunny day, just pass
it back to others, just starting or still learning.
Take and give

Regards, Gilbert

 

[Tom]

You will have to get used to the fact that the Ruby docs are horrible.

The *free* Ruby docs leave something to be desired. The Pickaxe book is
pretty good in a lot of ways, and I've also gotten a lot of value out of
the O'Reilly Ruby Pocket Reference I won at RubyConf.[/QUOTE]



Thanks for the recommendation. Most of the O'Reilly books have been helpful to
me so I'll check those out first. I've been seeing more references to Ruby
lately, I figure I might as well roll up my sleeves and get started.

Tom

 

[Gregory Seidman]

The *free* Ruby docs leave something to be desired. The Pickaxe book is
pretty good in a lot of ways, and I've also gotten a lot of value out of
the O'Reilly Ruby Pocket Reference I won at RubyConf.

Thanks for the recommendation. Most of the O'Reilly books have been
helpful to me so I'll check those out first. I've been seeing more
references to Ruby lately, I figure I might as well roll up my sleeves
and get started.[/QUOTE]

Be a little careful there. Notice that I'm recommending a pocket REFERENCE.
I already know Ruby. The best introduction to Ruby for me, coming from
other languages, was Why's (Poignant) Guide (google for it). The Pickaxe
(Programming Ruby <http://www.pragprog.com/titles/ruby> by Dave Thomas et
al.) is also a pretty good introduction. (Yes, the third edition will be
out soon covering Ruby 1.9, but I wouldn't wait for it. It may be worth it
to buy the 3rd edition later as well, but it's worth having the 2nd edition
now.) Just be careful of the difference between introductory/tutorial texts
and references. I can't recommend a specific O'Reilly book for learning the
language, not having looked at any, just the reference for looking up the
things I use rarely and always manage to forget (like whether regexes take
\a or \A and the difference between \z and \Z).

If you already knew all that, consider this a message to others who might
not.