gmane.comp.lang.ruby.documentation

unsuscribe

Carlos Zaltzman — 2013-05-08T15:19:41

unsuscribe

How to Unsubscribe

Gary Wright — 2013-05-08T14:43:16

Based on recent activity, many people don't know that sending "unsubscribe" to the primary list address is not the proper way to unsubscribe from the list.

To unsubscribe from the list, send a message with "unsubscribe" in the body to ruby-doc-ctl< at >ruby-lang.org

Note the "ruby-doc-ctl" part of the address.

guide

Barrie Stott — 2013-05-08T12:06:19

guide

(unknown)

Станислав — 2013-05-08T09:22:11

Unsubscribe

unsubscribed!

sengsengfyw — 2013-05-07T20:40:45

unsubscribed!

来自timelimit的邮件

timelimit — 2011-10-08T05:34:37

 unsubscribe

Documentation Translations

Chris White — 2011-08-20T01:11:54

Hello Everyone,

I had someone approach me earlier about helping out with Spanish translations of the Ruby documentation. With that in mind I'd like to get a feel for what, if at any, progress has been made to translate the Ruby documentation into something other than English (or Japanese if there is any untranslated documentation). 

The objective of this is to try and get a documentation translation team together, and start to centralize activity. Please respond on or off list if you have interest or know of existing translation projects.

Regards,
Chris White
http://www.twitter.com/cwgem

ObjectSpace#each_object example issue

Chris White — 2011-07-29T19:16:55

The documentation for ObjectSpace#each_object has the following sample code:

 *     a = 102.7
 *     b = 95       # Won't be returned
 *     c = 12345678987654321
 *     count = ObjectSpace.each_object(Numeric) {|x| p x }
 *     puts "Total count: #{count}"
 *
 *  <em>produces:</em>
 *
 *     12345678987654321
 *     102.7
 *     2.71828182845905
 *     3.14159265358979
 *     2.22044604925031e-16
 *     1.7976931348623157e+308
 *     2.2250738585072e-308
 *     Total count: 7

In this case, c, with the value of 12345678987654321 is supposed to show for being a Bignum. However on 64 bit systems this isn't the case:

= 64bit MacOSX Ruby SVN HEAD =
irb(main):001:0> puts RUBY_VERSION + " " + RUBY_PLATFORM + " " + RUBY_PATCHLEVEL.to_s
1.9.2 x86_64-darwin10.8.0 290
=> nil
irb(main):002:0> 12345678987654321.class
=> Fixnum

This won't show because as explained, "Immediate objects (Fixnums, Symbols true, false, and nil) are never returned." One a 32 bit system, however, this isn't an issue:

= 32bit Ubuntu Ruby SVN HEAD
irb(main):001:0> puts RUBY_VERSION + " " + RUBY_PLATFORM + " " + RUBY_PATCHLEVEL.to_s
1.9.4 i686-linux -1
=> nil
irb(main):002:0> 12345678987654321.class
=> Bignum

I see two possible solutions to this:

1) Use a number that produces Bignum on both 32 an 64 bit systems:

irb(main):003:0> 12345678987654321094903903903.class
=> Bignum

2) Split out the explanation to show 32 and 64 bit side by side?

3) Just add a side not explaining the issue with 32 and 64 bit differences

Also there might be another potential fix if there is some constant that holds the min and max values Bignum is capable of, but that's more of a feature request than a change in the docs.

- Chris
Twitter: < at >cwgem

(unknown)

Roger Newton — 2011-07-04T15:45:28

unsubscribe

Array and Enum: Elements or Objects?

Loren Sands-Ramshaw — 2011-05-13T15:01:40

The documentation in array.c and enum.c uses the terms elements and objects
inconsistently. Currently there are 100 elements and 18 objects in array.c
and 59 elements and 21 objects in enum.c. I think element is the most
widely-used term for things in an array. For enum I can see the argument for
object given the range of things that can be enumerable, but wikipedia uses
element to refer to the things that are being enumerated. Should I make
everything in array.c element and everything in enum.c object, or just
everything element? Or something else?

Thanks,
Loren

Date, Time, DateTime -- documentation improvements

mathew — 2011-05-06T14:06:34

Someone on Reddit recently pointed at the documentation for Date as an
example of Ruby being inferior to that other language, citing the
number of undocumented methods, and methods like floor() that have no
obvious meaning for a date.

So I'm considering taking a pass at cleaning up the RubyDoc for date.
Before I do, I'm wondering if there are any methods which aren't
supposed to be part of the API?  Things like dhms_to_delta and divmod
don't look as though they should be a guaranteed feature of a
date/time API.


mathew

Class:Hash

Slevin McGuigan — 2010-12-05T21:29:34

Hi *,

I am new to ruby and new to this mailinglist. I hope my question isn't too
simple to be coped with. But as I want to get involved in the ruby community
I choosed this one as a lightweight issue to start with.

I stumbled about the behaviour of Hash#key (which is a strange method
anyway, imho. I guess I won't ever use it). The behavior of #key isn't
obvious in case there is more then one occurance of the key

testhash = {
  '1' => 'a',
  '2' => 'b',
  '3' => 'a'
}
puts "#{testhash.key('a')}"         # => 1
testhash.delete('1')
puts "#{testhash.key('a')}"         # => 3

http://rdoc.info/docs/ruby-core/1.9.2/Hash sais that "Hashes enumerate their
values in the order that the corresponding keys were inserted" Hence the
behavior is following the documentation (or vice versa)

But both http://rdoc.info/docs/ruby-core/1.9.2/Hash#key-instance_method and
http://www.ruby-doc.org/ruby-1.9/classes/Hash.html#M000387 only say "Returns
the key for a given value. If not found, returns nil".

And question #1 is: What is the best place too look/the official
documentation? And is this mailing list the proper way to discuss
documentation flaws?
And question #1 is: Shouldn't there be something in the documentation of
hash#key like "... If there is more then one occurance of the key the first
value is returned"

Best Regards,
Slevin

--

My system: Ubuntu 9.10, ruby 1.9.1
egon< at >egon:/home/egon> uname -a
Linux egon 2.6.31-22-generic #68-Ubuntu SMP Tue Oct 26 16:38:35 UTC 2010
i686 GNU/Linux
egon< at >egon:/home/egon> cat /etc/lsb\-release
DISTRIB_ID=Ubuntu
DISTRIB_RELEASE=9.10
DISTRIB_CODENAME=karmic
DISTRIB_DESCRIPTION="Ubuntu 9.10"
egon< at >egon:/home/egon> ruby -v
ruby 1.9.1p243 (2009-07-16 revision 24175) [i486-linux]

Joseph Jones wants to be your friend on Windows Live

Joseph Jones — 2010-11-28T18:27:25

Joseph Jones wants to be your friend on Windows Live
<http://cid-a638a0cf4cfcdb5a.profile.live.com/?invite=d6649c6ff93220102%3aUwPoIyzHZBWQlCDyUezmSgSh6DPntoGXHKtE4rHD3%2bJ6YXaMoihio7HzknARcZ2%2b34eg76jsMetA9MOwmDMwqDw9BTNrx9sEnILqV4%2fYthSf%2fBZ%2bDXbn9wwSZ5nQBbml&ids=CSIyjIqUQLpXfdaqJdfWvc63iqxCGEK%2a%2aWpM7LqsNK6Gg15djxsBtPHN5yIldsDuHOUHGNtkkl6o%2a1Ih7GZc7fp5%2aAxLK7I78u5P4wDJzGXXp%2aJTdlG%21LUGZIZZYu30UkGn6TKw%24&Bsrc=EMINOO&Bpub=SN.Notifications>
""
View invitation
<http://cid-a638a0cf4cfcdb5a.profile.live.com/?invite=d6649c6ff93220102%3aUwPoIyzHZBWQlCDyUezmSgSh6DPntoGXHKtE4rHD3%2bJ6YXaMoihio7HzknARcZ2%2b34eg76jsMetA9MOwmDMwqDw9BTNrx9sEnILqV4%2fYthSf%2fBZ%2bDXbn9wwSZ5nQBbml&ids=CSIyjIqUQLpXfdaqJdfWvc63iqxCGEK%2a%2aWpM7LqsNK6Gg15djxsBtPHN5yIldsDuHOUHGNtkkl6o%2a1Ih7GZc7fp5%2aAxLK7I78u5P4wDJzGXXp%2aJTdlG%21LUGZIZZYu30UkGn6TKw%24&Bsrc=EMINOO&Bpub=SN.Notifications>
Notifications preferences
<http://profile.live.com/options/notifications/>
Microsoft privacy statement
<http://www.microsoft.com/info/privacy/default.mspx>
Microsoft Corporation, One Microsoft Way, Redmond, WA 98052

http://ruby-doc.org/core/classes/Dir.html#M002322 nits

Rich Morin — 2010-08-08T22:05:59

There is a formatting problem in the Dir.glob entry:

  http://ruby-doc.org/core/classes/Dir.html#M002322

It looks like a backslash is confusing things in the last entry
in the table.  What displays is:

  <code>
  </code>:  Escapes the next metacharacter.

Also, I don't see any places where backslashes are demonstrated in
the example area.


Finally, the entry says that * is / .* /x in regexp.  I think it's
actually closer to / [^/]* /.

-r

comments from an experienced programmer on ruby docs

2010-07-28T18:41:38

Hey there, I am learning ruby for my hard drive backup project:

http://www.subspacefield.org/security/hdb/

Ruby is a cool language, but the documentation is a little hard to
read.  Many people use the term "Foo#whatever" with the assumption
that one knows what it means - I originally assumed it was an instance
method, but now believe it is a class method.  Since it's a special
character, you can't really search google for it easily.

Regarding http://rubylearning.com/: the formatting of the text boxes
is awful, since at least on my computer, it requires manually scrolling
every one, effectively peering at the program through a tiny viewport.
The content, however, is very good.

One thing that needs discussion is how everything except ints and
floats (and perhaps some other types) are passed by reference.  I got
really bit by passing strings into constructors, and the constructor
later modified the string, and that changed the value of the thing I
passed in.  This is true for arrays as well, and any user-defined
objects.  Since this is a change from how many other scripting
languages work, you should point it out a little better (it is hinted
at).  In essence, you'll want to dup any parameter before modifying it
(unless again it is an integer or float).  I assume these are the
objects that correspond to "what fits in a register" in C.  I make it
a practice to dup everything that gets passed into a constructor.  In
any case, this is a lot closer to C than I expected.

Regarding:

http://www.ruby-lang.org/en/documentation/ruby-from-other-languages/to-ruby-from-python/

* The notions of equality (== vs eql?) differ from that of python.
* The keyword parameter stuff can be moved from the higher level page to this one,
  since it's targeted at python programmers.

Generally:

You should show how to delegate a method generically.  In other words,
"I don't know how the delegatee will implement this, how the caller
will invoke it, or whatever - I just want to pass calls to method blah
through"

Use of .document with RDoc

Barrie Stott — 2010-07-02T13:38:04

Suppose I've installed the rdoc (2.5.8) gem without creating any
documentation. It has a top level file, .document, that contains:

History.txt
README.txt
RI.txt
lib

I move to the directory .../gems/rdoc-2.5.8 and run the command:

rdoc --ri --op /tmp/doc

I expect to get all relevant ri documentation in /tmp/doc but I see
nothing corresponding to the .txt files mentioned in .document.

I would be grateful if someone could explain to me what I am doing
wrong and, even more importantly, what I should do to get the
documentation corresponding to the .txt files.

Barrie.

(unknown)

Skajn skajn — 2010-06-09T02:14:17

2.2     Usage of Commands

Problems moving from ri1.8 to ri1.9.1

Barrie Stott — 2010-05-21T18:44:26

I am running a Debian unstable GNU/Linux system and trying to move
from ruby1.8 to ruby1.9.1. As part of the exercise I wanted to be able
to use ri1.9.1 instead of ri1.8 but have had great trouble in trying
to create the .ri files for 1.9.1.

First I tried running the following to get 'system' .ri stuff:
rdoc1.9.1 -Y --format='ri' -M -U 2>/tmp/res2 1>/tmp/res1

I have no real confidence in the above command line but the man page
for rdoc1.9.1 wasn't very good and erroneous in parts. If someone
knows what the command line should be I'd be pleased to hear.

The file /tmp/res2 is a file of 13500 lines similar to:
Unrecognized directive 'body' in SystemExit/status-i.yaml

Apart from the last line that read, 'Generating RI...', every line was
of the form 'Unrecognized directive x in y'. This looks like a set of
error messages to me but I have no idea what to do about them. Help
would be appreciated.

An unrelated circumstance is an anomaly that I don't understand.
Running 'ri1.8 File::new' and 'ri1.9.1 File::new' gives different
results but I have only a single File/new-c.ri on the machine. Again,
if someone can shed light on this I'd be very grateful.

Here's my justification for my claim in the previous paragraph.
-I ran 'updatedb' followed by 'locate /File/new'. This gave four
files, all .yaml except for /usr/share/ri1.8/system/File/new-c.ri,
saying that there is a single /File/new-c.ri on my system.
-I ran 'ri1.8 File::new >/tmp/new1.8', 'ri1.9.1 File::new >/tmp/new1.9'
and 'diff U 0 /tmp/new1.{8,9}'. This gave me the stuff below
showing that ri1.8 and ri1.9.1 can give different results on the
same file.

Barrie.
-------------------------------------------
--- /tmp/new1.82010-05-21 18:41:27.000000000 +0100
+++ /tmp/new1.92010-05-21 18:41:55.000000000 +0100
< at >< at > -2,2 +2,4 < at >< at >
-     File.new(filename, mode="r")            => file
-     File.new(filename [, mode [, perm]])    => file
+     File.new(filename, mode="r" [, opt])            => file
+     File.new(filename [, mode [, perm]] [, opt])    => file
+
+     From Ruby 1.9.1
< at >< at > -6,7 +8,15 < at >< at >
-     ``r'') and returns a new +File+ object. See the description of
-     class +IO+ for a description of _mode_. The file mode may
-     optionally be specified as a +Fixnum+ by _or_-ing together the
-     flags (O_RDONLY etc, again described under +IO+). Optional
-     permission bits may be given in _perm_. These mode and permission
-     bits are platform dependent; on Unix systems, see +open(2)+ for
-     details.
+     ``r'') and returns a new +File+ object.
+
+     Parameters
+
+     See the description of class +IO+ for a description of _mode_. The
+     file mode may optionally be specified as a +Fixnum+ by _or_-ing
+     together the flags (O_RDONLY etc, again described under +IO+).
+
+     Optional permission bits may be given in _perm_. These mode and
+     permission bits are platform dependent; on Unix systems, see
+     +open(2)+ for details.
+
+     Optional _opt_ parameter is same as in <code.IO.open</code>.
+
+     Examples
-------------------------------------------

File#directory? docs

Ilkka Laukkanen — 2010-05-01T18:14:53

Hi,

I just noticed for the first time that if you have a symlink, say
"foo", that points at a directory, both

  File.symlink? 'foo'

and

  File.directory? 'foo'

return true. While this is a bit misleading in my opinion, it should
definitely be documented in File.directory?. So here's a tiny little
patch against trunk that documents this caveat in File#directory?.
What do you think?

Docs for String.split

Gabriel Gilder — 2010-01-20T18:23:20

Hi there,
Just joined to point out a small oversight in the Ruby docs - I looked into
the process for contributing documentation changes but it was a little over
my head. :) So I figured someone here could probably take care of it really
quickly.

So, the docs for String.split cover splitting by regex, but they don't
mention that if you have a capturing subpattern (or several) in your regex,
that gets included in the returned array.

For example:

"1, 2.34,56, 7".split(%r{(,\s*)}) #=> ["1", ", ", "2.34", ",", "56", ", ",
"7"]
"word :separator: word".split(/(:(\w+):)/) #=> ["word ", ":separator:",
"separator", " word"]

I've tested this in Ruby 1.8.7, but I imagine it works the same way in Ruby
1.9 as well, so both versions of the docs should probably be updated.

Thanks, please let me know if you have any questions!

-Gabriel


--------------------------------
Gabriel Gilder
Graphic Design & Web Programming
http://gabrielgilder.com
gabriel< at >gabrielgilder.com

How to fix docs for Zlib::GzipReader#wrap ?

Hugh Sasse — 2010-01-20T14:16:00

The docs for Zlib on line, for example 
http://ruby-doc.org/stdlib/libdoc/zlib/rdoc/classes/Zlib/GzipReader.html

have phrases such as:
  Further details of this method are in Zlib::GzipReader.new and
  ZLib::GzipReader.wrap. 

but wrap is not actually listed in that document.  I have found docs
for it in 
ruby-1.9.1-p376/ext/zlib/doc/zlib.rd
and in
ruby-1.8.7-p173/ext/zlib/doc/zlib.rd
[1], and I consider it fair enough that rdoc didn't pick this up 
(different directory, different format, different extension).
Because I don't do enough with C extensions, I don't know how to fix
the source to get this picked up correctly by rdoc.
ruby-1.8.7-p173/ext/zlib/zlib.c  has
    rb_define_singleton_method(cGzipFile, "wrap", rb_gzfile_s_wrap, -1);
but 
    cGzipFile = rb_define_class_under(mZlib, "GzipFile", rb_cObje ct);
and there doesn't seem to be much to say that wrap should appear as a 
method of GzipReader or GzipWriter, according to my quick searches.

Is it actually possible to document this in the source so Rdoc will
pick this up correctly?  Is there anything concise someone can point
me at that will enable me to write the comments in the right place
and style for something more useful to show up, even if perfection 
is not attained?  I don't mind trying to make something acceptable, but
I'm trying to fix some code using wrap, so don't want to spend too
long on the details of creating the docs, if that can be avoided.

        Thank you,
        Hugh

[1]
   It says:
--- Zlib::GzipReader.wrap(io) {|gz| ... }

    Creates a GzipReader object associated with ((|io|)), and
    executes the block with the newly created GzipReader object,
    just like File::open. The GzipReader object will be closed
    automatically after executing the block. If you want to keep
    the associated IO object opening, you may call
    ((<Zlib::GzipFile#finish>)) method in the block.