Documentation

[lemontree75]

Hi all,

I am starting to play with Ruby but I am really confused on where to
find decent documentation.
I was writing a simple program that uses Find to iterate over files and
calculates MD5 digests for every file. So for every found file I use
File.read to read it and compute the MD5. I have found the following
(frustrating) problems:

1) By looking at the documentation File.read doesn't exist as a method.
However by it seems that File is a subclass of IO that actually
contains read. But this is not clearly specified in the documentation
(it is only mentioned that it is closely associated with class IO,
whatever this means)

2) Exceptions... File.read raises an exception if, for example, I try
to read a file that requires higher access privileges. Again, the
documentation doesn't provide any kind of information of what type of
exceptions can be raised.

Is it RI the best source of documentation?
Where can I find a better one?

Thanks

 

[Manfred Stienstra]

Is it RI the best source of documentation?
Where can I find a better one?

Most of the documentation in Ri is very short, for more elaborate
information visit

http://www.ruby-doc.org
http://www.rubymanual.org

or buy a good Ruby book.

 

[lemontree75]

Manfred Stienstra ha scritto:

Most of the documentation in Ri is very short, for more elaborate
information visit

http://www.ruby-doc.org
http://www.rubymanual.org

I have already looked at them...
Maybe, since I am new to Ruby I am missing something but even there

1) No info about exceptions concerning File.read
2) Actually I cannot establish where File.read comes from
3) Errno::EACCES... What's that?!?! It is the name of the raised
exception that I catch with the rescue keyword. It works but
Errno::EACCES doesn't appear anywhere in the documentation!!!

or buy a good Ruby book.

I cannot buy a book to browse the documentation!

 

[Anselm]

http://www.ruby-doc.org
http://www.rubymanual.org

I did not know of rubymanual.org ! At a glance, the only difference
with ruby-doc.org's library documentation is the capacity to add notes.
(and the template of rubymanual is nicer)

Looking a bit deeper, rubymanual doesn't tell you about included
modules (What's the point of documentating Array if you don't have a
link to Enumerable?). And some of the documentation is incomplete (see
for instance http://www.rubymanual.org/module/Enumerable )

Why the duplicate effort ?

 

[Daniel Schierbeck]

I am starting to play with Ruby but I am really confused on where to
find decent documentation.

Coming from the world of PHP (yes, I'm a bit ashamed...), I must say
that the Ruby documentation is absolutely terrible. I really think the
best thing would be to document the core and the standard library on a
specialized wiki (preferably with a REST interface.)

Hell, the HTML outputted by RDoc uses frames! That makes it a bit more
difficult to link directly to classes and methods.


Daniel

 

[Dale]

1) By looking at the documentation File.read doesn't exist as a method.
However by it seems that File is a subclass of IO that actually
contains read. But this is not clearly specified in the documentation
(it is only mentioned that it is closely associated with class IO,
whatever this means)

The online version of Programming Ruby (1st edition) makes this clear.
Not that it links directly to it.

<http://www.ruby-doc.org/docs/ProgrammingRuby/>

I'd suggest you use Programming Ruby instead.

 

[Kero]

Most of the documentation in Ri is very short, for more elaborate

I have already looked at them...
Maybe, since I am new to Ruby I am missing something but even there

1) No info about exceptions concerning File.read
2) Actually I cannot establish where File.read comes from

Indeed, `ri File` does not tell "File < IO" at the top line.
That's wrong.
(and yes, I agree ruby docs are terse and lacking too often.)

3) Errno::EACCES... What's that?!?! It is the name of the raised
exception that I catch with the rescue keyword. It works but
Errno::EACCES doesn't appear anywhere in the documentation!!!

there are a lot of these errors. the leading 'E' reiterates it's an Error.

In this case, there is an "access" problem. From here on, you'll have to
figure out yourself why you have no access.

Another way to find these is `man read` on a *nix (posix?) system.
Works for a lot of other method names from various classes.

Finally, it's an exception. It's not supposed to happen. I do not believe
you want to prepare for all exceptions that can occur (that's why the Ruby
interpreter 'rescues' it and throws it in your face when it happens.) Otoh,
if exceptions do not carry meaningful content, they do not help you. For me,
Errno::EACCESS is very meaningful content.

I cannot buy a book to browse the documentation!

But you can certainly use a good book to learn "File < IO"
which you will have to learn anyway.

Bye,
Kero.

 

[Robert Klemme]

Indeed, `ri File` does not tell "File < IO" at the top line.
That's wrong.
(and yes, I agree ruby docs are terse and lacking too often.)

True. But also (see below).

But you can certainly use a good book to learn "File < IO"
which you will have to learn anyway.

IRB is also helpful to sort these things out:
=> [File, IO, File::Constants, Enumerable, Object, Kernel]
=> ["flock", "chmod", "truncate", "atime", "path", "chown", "mtime",
"ctime", "lstat"]

or, more generally for the whole hierarchy:
sup.instance_methods; sup}
["flock", "chmod", "truncate", "atime", "path", "chown", "mtime",
"ctime", "lstat"]
["respond_to?", "select", "puts", "<<", "to_a", "eof", "type", "ungetc",
"display", "protected_methods", "partition", "close_write", "syswri
te", "eql?", "grep", "instance_variable_set", "ioctl", "is_a?", "sync",
"hash", "to_s", "send", "reject", "gets", "sync=", "flush", "write",
"class", "isatty", "tainted?", "private_methods", "member?",
"__send__", "sysread", "find", "printf", "untaint", "method", "eof?",
"fcntl",
"each_with_index", "each_line", "id", "lineno", "to_i", "collect",
"readline", "inspect", "instance_eval", "close", "all?", "clone", "entri
es", "read", "lineno=", "tell", "public_methods", "fileno", "extend",
"freeze", "detect", "print", "rewind", "zip", "each_byte", "pid", "__i
d__", "readpartial", "==", "methods", "map", "readlines", "===", "any?",
"stat", "tty?", "seek", "sort", "getc", "nil?", "dup", "instance_va
riables", "binmode", "include?", "min", "instance_of?", "to_io", "pos",
"find_all", "putc", "closed?", "each", "object_id", "=~", "readchar"
, "pos=", "close_read", "inject", "singleton_methods", "reopen",
"equal?", "taint", "sort_by", "frozen?", "instance_variable_get", "max", "s
ysseek", "fsync", "kind_of?"]
[]
["find_all", "sort_by", "collect", "detect", "max", "sort", "partition",
"any?", "reject", "zip", "find", "min", "member?", "entries", "inje
ct", "all?", "select", "each_with_index", "grep", "map", "include?"]
[]
=> Kernel
sup.instance_methods).unshift cl); sup}
(irb):13: warning: parenthesize argument(s) for future version
[File, "flock", "chmod", "truncate", "atime", "path", "chown", "mtime",
"ctime", "lstat"]
[IO, "respond_to?", "select", "puts", "<<", "to_a", "eof", "type",
"ungetc", "display", "protected_methods", "partition", "close_write", "sy
swrite", "eql?", "grep", "instance_variable_set", "ioctl", "is_a?",
"sync", "hash", "to_s", "send", "reject", "gets", "sync=", "flush", "wri
te", "class", "isatty", "tainted?", "private_methods", "member?",
"__send__", "sysread", "find", "printf", "untaint", "method", "eof?", "fcn
tl", "each_with_index", "each_line", "id", "lineno", "to_i", "collect",
"readline", "inspect", "instance_eval", "close", "all?", "clone", "e
ntries", "read", "lineno=", "tell", "public_methods", "fileno",
"extend", "freeze", "detect", "print", "rewind", "zip", "each_byte", "pid",
"__id__", "readpartial", "==", "methods", "map", "readlines", "===",
"any?", "stat", "tty?", "seek", "sort", "getc", "nil?", "dup", "instanc
e_variables", "binmode", "include?", "min", "instance_of?", "to_io",
"pos", "find_all", "putc", "closed?", "each", "object_id", "=~", "readc
har", "pos=", "close_read", "inject", "singleton_methods", "reopen",
"equal?", "taint", "sort_by", "frozen?", "instance_variable_get", "max"
, "sysseek", "fsync", "kind_of?"]
[File::Constants]
[Enumerable, "find_all", "sort_by", "collect", "detect", "max", "sort",
"partition", "any?", "reject", "zip", "find", "min", "member?", "ent
ries", "inject", "all?", "select", "each_with_index", "grep", "map",
"include?"]
[Object]
=> Kernel

Kind regards

robert

 

[jmg3000]

I did not know of rubymanual.org ! At a glance, the only difference
with ruby-doc.org's library documentation is the capacity to add notes.
(and the template of rubymanual is nicer)

Looking a bit deeper, rubymanual doesn't tell you about included
modules (What's the point of documentating Array if you don't have a
link to Enumerable?). And some of the documentation is incomplete (see
for instance http://www.rubymanual.org/module/Enumerable )

Why the duplicate effort ?

The official online "commentable" Ruby docs (a la the PHP docs) are
facilitated by the Rannotate software (http://rannotate.rubyforge.org/)
and are at: http://ruby.outertrack.com/ (as linked to from the
Rannotate home page).

It's not clear why http://www.rubymanual.org/ was created.

The author of Rannotate (Conor Hunt) is actively working on adding
features and removing bugs, and could always use a hand.

---John

 

[jmg3000]

Hi all,

I am starting to play with Ruby but I am really confused on where to
find decent documentation.
[snip]

The primary web site for ruby docs is: http://www.ruby-doc.org/ .
Linked to from that site are (among other good docs) the API docs,
which are generated directly from the Ruby source code files:

http://www.ruby-doc.org/core/
http://www.ruby-doc.org/stdlib/

Aside from those, the other two primary places to look for help docs
are:

http://wiki.rubygarden.org/Ruby -- the Ruby wiki.
http://www.rubygarden.org/faq -- the Ruby faq (currently down).

Is it RI the best source of documentation?

It's supposed to be, but it needs more contributions. This is why we
have http://ruby.outertrack.com/ -- to help fold good user-submitted
comments into the Ruby sources (which means you'll be able to read them
via ri as well).

---John

 

[Erik Hollensbe]

1) No info about exceptions concerning File.read
2) Actually I cannot establish where File.read comes from
3) Errno::EACCES... What's that?!?! It is the name of the raised
exception that I catch with the rescue keyword. It works but
Errno::EACCES doesn't appear anywhere in the documentation!!!

(This could be slightly incorrect, but is useful for the purpose of
this discussion. I'd love to hear how this /actually/ works in ruby.)

File (and consequently IO) exceptions are not really exceptions, but
mirrored from the constants from 'errno.h', which is normally in
/usr/include. If you're on a windows system, it's somewhere in your
stdlib include path.

If you're on a unix machine, you can type 'man 2 open' to get a list of
these constants and what they mean.

From the manual (OS X 10.4):

[EACCES] Search permission is denied for a component of the
path prefix.

[EACCES] The required permissions (for reading and/or writing)
are denied for the given flags.

[EACCES] O_CREAT is specified, the file does not exist, and the
directory in which it is to be created does not permit
writing.