RDoc Struct and random

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@5340 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

5 files changed, 282 insertions, 2 deletions

diff --git a/ChangeLog b/ChangeLog
index 882d2ac236..fe5e2c404c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+Mon Dec 29 05:05:51 2003  Dave Thomas  <dave@wireless_3.local.thomases.com>
+
+	* struct.c, random: Add RDoc comments
+
 Mon Dec 29 02:25:00 2003  Gavin Sinclair <gsinclair@soyabean.com.au>
 
 	* lib/optparse.rb: Improved documentation.
diff --git a/lib/rdoc/parsers/parse_c.rb b/lib/rdoc/parsers/parse_c.rb
index b8296f569d..eb1083df24 100644
--- a/lib/rdoc/parsers/parse_c.rb
+++ b/lib/rdoc/parsers/parse_c.rb
@@ -262,7 +262,9 @@ module RDoc
         |type, var_name, meth_name, meth_body, param_count, source_file|
        #" 
         next if meth_name == "initialize_copy"
-        next if var_name  == "ruby_top_self"
+
+        # Ignore top-object and weird struct.c dynamic stuff
+        next if var_name  == "ruby_top_self" || var_name == "nstr"
                           
         var_name = "rb_cObject" if var_name == "rb_mKernel"
         handle_method(type, var_name, meth_name, 
diff --git a/object.c b/object.c
index ea7aa9ac58..90b76979a4 100644
--- a/object.c
+++ b/object.c
@@ -729,7 +729,7 @@ rb_obj_frozen_p(obj)
 
 
 /*
- * Document-class: NillClass
+ * Document-class: NilClass
  *
  *  The class of the singleton object <code>nil</code>.
  */
diff --git a/random.c b/random.c
index 86c8198d41..9a843f2aff 100644
--- a/random.c
+++ b/random.c
@@ -172,6 +172,20 @@ random_seed()
     return tv.tv_sec ^ tv.tv_usec ^ getpid() ^ n++;
 }
 
+/*
+ *  call-seq:
+ *     srand(number=0)    => old_seed
+ *  
+ *  Seeds the pseudorandom number generator to the value of
+ *  <i>number</i>.<code>to_i.abs</code>. If <i>number</i> is omitted
+ *  or zero, seeds the generator using a combination of the time, the
+ *  process id, and a sequence number. (This is also the behavior if
+ *  <code>Kernel::rand</code> is called without previously calling
+ *  <code>srand</code>, but without the sequence.) By setting the seed
+ *  to a known value, scripts can be made deterministic during testing.
+ *  The previous seed value is returned. Also see <code>Kernel::rand</code>.
+ */
+
 static VALUE
 rb_f_srand(argc, argv, obj)
     int argc;
@@ -193,6 +207,26 @@ rb_f_srand(argc, argv, obj)
     return ULONG2NUM(old);
 }
 
+/*
+ *  call-seq:
+ *     rand(max=0)    => number
+ *  
+ *  Converts <i>max</i> to an integer using max1 =
+ *  max<code>.to_i.abs</code>. If the result is zero, returns a
+ *  pseudorandom floating point number greater than or equal to 0.0 and
+ *  less than 1.0. Otherwise, returns a pseudorandom integer greater
+ *  than or equal to zero and less than max1. <code>Kernel::srand</code>
+ *  may be used to ensure repeatable sequences of random numbers between
+ *  different runs of the program. Ruby currently uses a modified
+ *  Mersenne Twister with a period of 219937-1.
+ *     
+ *     srand 1234                 #=> 0
+ *     [ rand,  rand ]            #=> [0.191519450163469, 0.49766366626136]
+ *     [ rand(10), rand(1000) ]   #=> [6, 817]
+ *     srand 1234                 #=> 1234
+ *     [ rand,  rand ]            #=> [0.191519450163469, 0.49766366626136]
+ */
+
 static VALUE
 rb_f_rand(argc, argv, obj)
     int argc;
diff --git a/struct.c b/struct.c
index 73a7f5aeea..9ad30460ff 100644
--- a/struct.c
+++ b/struct.c
@@ -54,6 +54,18 @@ rb_struct_s_members(obj)
     return ary;
 }
 
+/*
+ *  call-seq:
+ *     struct.members    => array
+ *  
+ *  Returns an array of strings representing the names of the instance
+ *  variables.
+ *     
+ *     Customer = Struct.new(:name, :address, :zip)
+ *     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
+ *     joe.members   #=> ["name", "address", "zip"]
+ */
+
 static VALUE
 rb_struct_members(obj)
     VALUE obj;
@@ -223,6 +235,40 @@ rb_struct_define(name, va_alist)
     return make_struct(nm, ary, rb_cStruct);
 }
 
+/*
+ *  call-seq:
+ *     Struct.new( [aString] [, aSym]+> )    => StructClass
+ *     StructClass.new(arg, ...)             => obj
+ *     StructClass[arg, ...]                 => obj
+ *
+ *  Creates a new class, named by <i>aString</i>, containing accessor
+ *  methods for the given symbols. If the name <i>aString</i> is
+ *  omitted, an anonymous structure class will be created. Otherwise,
+ *  the name of this struct will appear as a constant in class
+ *  <code>Struct</code>, so it must be unique for all
+ *  <code>Struct</code>s in the system and should start with a capital
+ *  letter. Assigning a structure class to a constant effectively gives
+ *  the class the name of the constant.
+ *     
+ *  <code>Struct::new</code> returns a new <code>Class</code> object,
+ *  which can then be used to create specific instances of the new
+ *  structure. The number of actual parameters must be
+ *  less than or equal to the number of attributes defined for this
+ *  class; unset parameters default to \nil{}.  Passing too many
+ *  parameters will raise an \E{ArgumentError}.
+ *
+ *  The remaining methods listed in this section (class and instance)
+ *  are defined for this generated class. 
+ *     
+ *     # Create a structure with a name in Struct
+ *     Struct.new("Customer", :name, :address)    #=> Struct::Customer
+ *     Struct::Customer.new("Dave", "123 Main")   #=> #<Struct::Customer name="Dave", address="123 Main">
+ *     
+ *     # Create a structure named by its constant
+ *     Customer = Struct.new(:name, :address)     #=> Customer
+ *     Customer.new("Dave", "123 Main")           #=> #<Customer name="Dave", address="123 Main">
+ */
+
 static VALUE
 rb_struct_s_def(argc, argv, klass)
     int argc;
@@ -249,6 +295,9 @@ rb_struct_s_def(argc, argv, klass)
     return st;
 }
 
+/*
+ */
+
 static VALUE
 rb_struct_initialize(self, values)
     VALUE self, values;
@@ -322,6 +371,24 @@ rb_struct_new(klass, va_alist)
     return rb_class_new_instance(size, mem, klass);
 }
 
+/*
+ *  call-seq:
+ *     struct.each {|obj| block }  => struct
+ *  
+ *  Calls <i>block</i> once for each instance variable, passing the
+ *  value as a parameter.
+ *     
+ *     Customer = Struct.new(:name, :address, :zip)
+ *     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
+ *     joe.each {|x| puts(x) }
+ *     
+ *  <em>produces:</em>
+ *     
+ *     Joe Smith
+ *     123 Maple, Anytown NC
+ *     12345
+ */
+
 static VALUE
 rb_struct_each(s)
     VALUE s;
@@ -334,6 +401,24 @@ rb_struct_each(s)
     return s;
 }
 
+/*
+ *  call-seq:
+ *     struct.each_pair {|sym, obj| block }     => struct
+ *  
+ *  Calls <i>block</i> once for each instance variable, passing the name
+ *  (as a symbol) and the value as parameters.
+ *     
+ *     Customer = Struct.new(:name, :address, :zip)
+ *     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
+ *     joe.each_pair {|name, value| puts("#{name} => #{value}") }
+ *     
+ *  <em>produces:</em>
+ *     
+ *     name => Joe Smith
+ *     address => 123 Maple, Anytown NC
+ *     zip => 12345
+ */
+
 static VALUE
 rb_struct_each_pair(s)
     VALUE s;
@@ -387,6 +472,14 @@ inspect_struct(s)
     return str;
 }
 
+/*
+ * call-seq:
+ *   struct.to_s      => string
+ *   struct.inspect   => string
+ *
+ * Describe the contents of this struct in a string.
+ */
+
 static VALUE
 rb_struct_inspect(s)
     VALUE s;
@@ -402,6 +495,18 @@ rb_struct_inspect(s)
     return rb_protect_inspect(inspect_struct, s, 0);
 }
 
+/*
+ *  call-seq:
+ *     struct.to_a     => array
+ *     struct.values   => array
+ *  
+ *  Returns the values for this instance as an array.
+ *     
+ *     Customer = Struct.new(:name, :address, :zip)
+ *     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
+ *     joe.to_a[1]   #=> "123 Maple, Anytown NC"
+ */
+
 static VALUE
 rb_struct_to_a(s)
     VALUE s;
@@ -448,6 +553,25 @@ rb_struct_aref_id(s, id)
     return Qnil;		/* not reached */
 }
 
+/*
+ *  call-seq:
+ *     struct[symbol]    => anObject
+ *     struct[fixnum]    => anObject 
+ *  
+ *  Attribute Reference---Returns the value of the instance variable
+ *  named by <i>symbol</i>, or indexed (0..length-1) by
+ *  <i>fixnum</i>. Will raise <code>NameError</code> if the named
+ *  variable does not exist, or <code>IndexError</code> if the index is
+ *  out of range.
+ *     
+ *     Customer = Struct.new(:name, :address, :zip)
+ *     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
+ *     
+ *     joe["name"]   #=> "Joe Smith"
+ *     joe[:name]    #=> "Joe Smith"
+ *     joe[0]        #=> "Joe Smith"
+ */
+
 VALUE
 rb_struct_aref(s, idx)
     VALUE s, idx;
@@ -493,6 +617,27 @@ rb_struct_aset_id(s, id, val)
     rb_name_error(id, "no member '%s' in struct", rb_id2name(id));
 }
 
+/*
+ *  call-seq:
+ *     struct[symbol] = obj    => obj
+ *     struct[fixnum] = obj    => obj
+ *  
+ *  Attribute Assignment---Assigns to the instance variable named by
+ *  <i>symbol</i> or <i>fixnum</i> the value <i>obj</i> and
+ *  returns it. Will raise a <code>NameError</code> if the named
+ *  variable does not exist, or an <code>IndexError</code> if the index
+ *  is out of range.
+ *     
+ *     Customer = Struct.new(:name, :address, :zip)
+ *     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
+ *     
+ *     joe["name"] = "Luke"
+ *     joe[:zip]   = "90210"
+ *     
+ *     joe.name   #=> "Luke"
+ *     joe.zip    #=> "90210"
+ */
+
 VALUE
 rb_struct_aset(s, idx, val)
     VALUE s, idx, val;
@@ -526,6 +671,22 @@ struct_entry(s, n)
     return rb_struct_aref(s, LONG2NUM(n));
 }
 
+/* 
+ * call-seq:
+ *   struct.values_at(selector,... )  => an_array
+ *
+ *   Returns an array containing the elements in
+ *   _self_ corresponding to the given selector(s). The selectors
+ *   may be either integer indices or ranges. 
+ *   See also </code>.select<code>.
+ * 
+ *      a = %w{ a b c d e f }
+ *      a.values_at(1, 3, 5)
+ *      a.values_at(1, 3, 5, 7)
+ *      a.values_at(-1, -3, -5, -7)
+ *      a.values_at(1..3, 2...5)
+ */
+
 static VALUE
 rb_struct_values_at(argc, argv, s)
     int argc;
@@ -535,6 +696,26 @@ rb_struct_values_at(argc, argv, s)
     return rb_values_at(s, RSTRUCT(s)->len, argc, argv, struct_entry);
 }
 
+/*
+ *  call-seq:
+ *     struct.select(fixnum, ... )   => array
+ *     struct.select {|i| block }    => array
+ *  
+ *  The first form returns an array containing the elements in
+ *  <i>struct</i> corresponding to the given indices. The second
+ *  form invokes the block passing in successive elements from
+ *  <i>struct</i>, returning an array containing those elements
+ *  for which the block returns a true value (equivalent to
+ *  <code>Enumerable#select</code>).
+ *     
+ *     Lots = Struct.new(:a, :b, :c, :d, :e, :f)
+ *     l = Lots.new(11, 22, 33, 44, 55, 66)
+ *     l.select(1, 3, 5)               #=> [22, 44, 66]
+ *     l.select(0, 2, 4)               #=> [11, 33, 55]
+ *     l.select(-1, -3, -5)            #=> [66, 44, 22]
+ *     l.select {|v| (v % 2).zero? }   #=> [22, 44, 66]
+ */
+
 static VALUE
 rb_struct_select(argc, argv, s)
     int argc;
@@ -557,6 +738,23 @@ rb_struct_select(argc, argv, s)
     return result;
 }
 
+/*
+ *  call-seq:
+ *     struct == other_struct     => true or false
+ *  
+ *  Equality---Returns <code>true</code> if <i>other_struct</i> is
+ *  equal to this one: they must be of the same class as generated by
+ *  <code>Struct::new</code>, and the values of all instance variables
+ *  must be equal (according to <code>Object#==</code>).
+ *     
+ *     Customer = Struct.new(:name, :address, :zip)
+ *     joe   = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
+ *     joejr = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
+ *     jane  = Customer.new("Jane Doe", "456 Elm, Anytown NC", 12345)
+ *     joe == joejr   #=> true
+ *     joe == jane    #=> false
+ */
+
 static VALUE
 rb_struct_equal(s, s2)
     VALUE s, s2;
@@ -576,6 +774,13 @@ rb_struct_equal(s, s2)
     return Qtrue;
 }
 
+/*
+ * call-seq:
+ *   struct.hash   => fixnum
+ *
+ * Return a hash value based on this struct's contents.
+ */
+
 static VALUE
 rb_struct_hash(s)
     VALUE s;
@@ -592,6 +797,14 @@ rb_struct_hash(s)
     return LONG2FIX(h);
 }
 
+/*
+ * code-seq:
+ *   struct.eql?(other)   => true or false
+ *
+ * Two structures are equal if they are the same object, or if all their
+ * fields are equal (using <code>eql?</code>).
+ */
+
 static VALUE
 rb_struct_eql(s, s2)
     VALUE s, s2;
@@ -611,6 +824,18 @@ rb_struct_eql(s, s2)
     return Qtrue;
 }
 
+/*
+ *  call-seq:
+ *     struct.length    => fixnum
+ *     struct.size      => fixnum
+ *  
+ *  Returns the number of instance variables.
+ *     
+ *     Customer = Struct.new(:name, :address, :zip)
+ *     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
+ *     joe.length   #=> 3
+ */
+
 static VALUE
 rb_struct_size(s)
     VALUE s;
@@ -618,6 +843,21 @@ rb_struct_size(s)
     return LONG2FIX(RSTRUCT(s)->len);
 }
 
+/*
+ *  A <code>Struct</code> is a convenient way to bundle a number of
+ *  attributes together, using accessor methods, without having to write
+ *  an explicit class.
+ *     
+ *  The <code>Struct</code> class is a generator of specific classes,
+ *  each one of which is defined to hold a set of variables and their
+ *  accessors. In these examples, we'll call the generated class
+ *  ``<i>Customer</i>Class,'' and we'll show an example instance of that
+ *  class as ``<i>Customer</i>Inst.''
+ *     
+ *  In the descriptions that follow, the parameter <i>symbol</i> refers
+ *  to a symbol, which is either a quoted string or a
+ *  <code>Symbol</code> (such as <code>:name</code>).
+ */
 void
 Init_Struct()
 {