* struct.c: Improve documentation: replace "instance variable" with

  "member", recommend the use of a block to customize structs, note
  that member accessors are created, general cleanup.


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

1 files changed, 91 insertions, 92 deletions

diff --git a/struct.c b/struct.c
index 9365ffe90d..4356f0013f 100644
--- a/struct.c
+++ b/struct.c
@@ -73,8 +73,7 @@ rb_struct_s_members_m(VALUE klass)
  *  call-seq:
  *     struct.members    -> array
  *
- *  Returns an array of symbols representing the names of the instance
- *  variables.
+ *  Returns the struct members as an array of symbols:
  *
  *     Customer = Struct.new(:name, :address, :zip)
  *     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
@@ -290,22 +289,29 @@ rb_struct_define(const char *name, ...)
 
 /*
  *  call-seq:
- *     Struct.new( [aString] [, aSym]+> )                         -> StructClass
- *     Struct.new( [aString] [, aSym]+> ) {|StructClass| block }  -> StructClass
- *     StructClass.new(arg, ...)                                  -> obj
- *     StructClass[arg, ...]                                      -> obj
+ *    Struct.new([class_name] [, member_name]+>)                        -> StructClass
+ *    Struct.new([class_name] [, member_name]+>) {|StructClass| block } -> StructClass
+ *    StructClass.new(value, ...)                                       -> obj
+ *    StructClass[value, ...]                                           -> 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.
+ *  The first two forms are used to create a new Struct subclass +class_name+
+ *  that can contain a value for each +member_name+.  This subclass can be
+ *  used to create instances of the structure like any other Class.
  *
- *  If a block is given, it will be evaluated in the context of
- *  <i>StructClass</i>, passing <i>StructClass</i> as a parameter.
+ *  If the +class_name+ is omitted an anonymous structure class will be
+ *  created.  Otherwise, the name of this struct will appear as a constant in
+ *  class Struct, so it must be unique for all Structs in the system and
+ *  must start with a capital letter.  Assigning a structure class to a
+ *  constant also gives the class the name of the constant.
+ *
+ *     # Create a structure with a name under Struct
+ *     Struct.new("Customer", :name, :address)
+ *     #=> Struct::Customer
+ *     Struct::Customer.new("Dave", "123 Main")
+ *     #=> #<struct Struct::Customer name="Dave", address="123 Main">
+ *
+ *  If a block is given it will be evaluated in the context of
+ *  +StructClass+, passing the created class as a parameter:
  *
  *     Customer = Struct.new(:name, :address) do
  *       def greeting
@@ -314,23 +320,19 @@ rb_struct_define(const char *name, ...)
  *     end
  *     Customer.new("Dave", "123 Main").greeting  # => "Hello Dave!"
  *
- *  <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 <code>nil</code>.  Passing too many
- *  parameters will raise an <code>ArgumentError</code>.
- *
- *  The remaining methods listed in this section (class and instance)
- *  are defined for this generated class.
+ *  This is the recommended way to customize a struct.  Subclassing an
+ *  anonymous struct creates an extra anonymous class that will never be used.
  *
- *     # Create a structure with a name in Struct
- *     Struct.new("Customer", :name, :address)    #=> Struct::Customer
- *     Struct::Customer.new("Dave", "123 Main")   #=> #<struct Struct::Customer name="Dave", address="123 Main">
+ *  The last two forms create a new instance of a struct subclass.  The number
+ *  of +value+ parameters must be less than or equal to the number of
+ *  attributes defined for the structure.  Unset parameters default to +nil+.
+ *  Passing too many parameters will raise an ArgumentError.
  *
  *     # Create a structure named by its constant
- *     Customer = Struct.new(:name, :address)     #=> Customer
- *     Customer.new("Dave", "123 Main")           #=> #<struct Customer name="Dave", address="123 Main">
+ *     Customer = Struct.new(:name, :address)
+ *     #=> Customer
+ *     Customer.new("Dave", "123 Main")
+ *     #=> #<struct Customer name="Dave", address="123 Main">
  */
 
 static VALUE
@@ -465,16 +467,14 @@ rb_struct_size(VALUE s);
  *     struct.each {|obj| block }  -> struct
  *     struct.each                 -> an_enumerator
  *
- *  Calls <i>block</i> once for each instance variable, passing the
- *  value as a parameter.
- *
- *  If no block is given, an enumerator is returned instead.
+ *  Yields the value of each struct member in order.  If no block is given an
+ *  enumerator is returned.
  *
  *     Customer = Struct.new(:name, :address, :zip)
  *     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
  *     joe.each {|x| puts(x) }
  *
- *  <em>produces:</em>
+ *  Produces:
  *
  *     Joe Smith
  *     123 Maple, Anytown NC
@@ -498,16 +498,14 @@ rb_struct_each(VALUE s)
  *     struct.each_pair {|sym, obj| block }     -> struct
  *     struct.each_pair                         -> an_enumerator
  *
- *  Calls <i>block</i> once for each instance variable, passing the name
- *  (as a symbol) and the value as parameters.
- *
- *  If no block is given, an enumerator is returned instead.
+ *  Yields the name and value of each struct member in order.  If no block is
+ *  given an enumerator is returned.
  *
  *     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>
+ *  Produces:
  *
  *     name => Joe Smith
  *     address => 123 Maple, Anytown NC
@@ -596,7 +594,7 @@ rb_struct_inspect(VALUE s)
  *     struct.to_a     -> array
  *     struct.values   -> array
  *
- *  Returns the values for this instance as an array.
+ *  Returns the values for this struct as an Array.
  *
  *     Customer = Struct.new(:name, :address, :zip)
  *     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
@@ -613,8 +611,7 @@ rb_struct_to_a(VALUE s)
  *  call-seq:
  *     struct.to_h     -> hash
  *
- *  Returns the values for this instance as a hash with keys
- *  corresponding to the instance variable name.
+ *  Returns a Hash containing the names and values for the struct's members.
  *
  *     Customer = Struct.new(:name, :address, :zip)
  *     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
@@ -669,14 +666,12 @@ rb_struct_aref_id(VALUE s, ID id)
 
 /*
  *  call-seq:
- *     struct[symbol]    -> anObject
- *     struct[fixnum]    -> anObject
+ *     struct[member]   -> anObject
+ *     struct[index]    -> 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.
+ *  Attribute Reference---Returns the value of the given struct +member+ or
+ *  the member at the given +index+.   Raises NameError if the +member+ does
+ *  not exist and IndexError if the +index+ is out of range.
  *
  *     Customer = Struct.new(:name, :address, :zip)
  *     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
@@ -742,14 +737,12 @@ rb_struct_aset_id(VALUE s, ID id, VALUE val)
 
 /*
  *  call-seq:
- *     struct[symbol] = obj    -> obj
- *     struct[fixnum] = obj    -> obj
+ *     struct[name]  = obj    -> obj
+ *     struct[index] = 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.
+ *  Attribute Assignment---Sets the value of the given struct +member+ or
+ *  the member at the given +index+.  Raises NameError if the +name+ does not
+ *  exist and IndexError if the +index+ is out of range.
  *
  *     Customer = Struct.new(:name, :address, :zip)
  *     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
@@ -799,19 +792,17 @@ struct_entry(VALUE s, long n)
 }
 
 /*
- * call-seq:
- *   struct.values_at(selector,... )  -> an_array
+ *  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>.
+ *  Returns the struct member values for each +selector+ as an Array.  A
+ *  +selector+ may be either an Integer offset or a Range of offsets (as in
+ *  Array#values_at).
+ *
+ *     Customer = Struct.new(:name, :address, :zip)
+ *     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
+ *     joe.values_at 0, 2 #=> ["Joe Smith", 12345]
  *
- *      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
@@ -825,10 +816,9 @@ rb_struct_values_at(int argc, VALUE *argv, VALUE s)
  *     struct.select {|i| block }    -> array
  *     struct.select                 -> an_enumerator
  *
- *  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>).
+ *  Yields each member value from the struct to the block and returns an Array
+ *  containing the member values from the +struct+ for which the given block
+ *  returns a true value (equivalent to Enumerable#select).
  *
  *     Lots = Struct.new(:a, :b, :c, :d, :e, :f)
  *     l = Lots.new(11, 22, 33, 44, 55, 66)
@@ -871,12 +861,10 @@ recursive_equal(VALUE s, VALUE s2, int recur)
 
 /*
  *  call-seq:
- *     struct == other_struct     -> true or false
+ *     struct == other     -> 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>).
+ *  Equality---Returns +true+ if +other+ has the same struct subclass and has
+ *  equal member values (according to Object#==).
  *
  *     Customer = Struct.new(:name, :address, :zip)
  *     joe   = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
@@ -923,7 +911,7 @@ recursive_hash(VALUE s, VALUE dummy, int recur)
  * call-seq:
  *   struct.hash   -> fixnum
  *
- * Return a hash value based on this struct's contents.
+ * Returns a hash value based on this struct's contents (see Object#hash).
  */
 
 static VALUE
@@ -952,8 +940,9 @@ recursive_eql(VALUE s, VALUE s2, int recur)
  * call-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>).
+ * Hash equality---+other+ and +struct+ refer to the same hash key if they
+ * have the same struct subclass and have equal member values (according to
+ * Object#eql?).
  */
 
 static VALUE
@@ -974,7 +963,7 @@ rb_struct_eql(VALUE s, VALUE s2)
  *     struct.length    -> fixnum
  *     struct.size      -> fixnum
  *
- *  Returns the number of instance variables.
+ *  Returns the number of struct members.
  *
  *     Customer = Struct.new(:name, :address, :zip)
  *     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
@@ -988,19 +977,29 @@ rb_struct_size(VALUE s)
 }
 
 /*
- *  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.
+ *  A Struct is a convenient way to bundle a number of attributes together,
+ *  using accessor methods, without having to write an explicit class.
+ *
+ *  The Struct class generates new subclasses that hold a set of members and
+ *  their values.  For each member a reader and writer method is created
+ *  similar to Module#attr_accessor.
+ *
+ *     Customer = Struct.new(:name, :address) do
+ *       def greeting
+ *         "Hello #{name}!"
+ *       end
+ *     end
+ *
+ *     dave = Customer.new("Dave", "123 Main")
+ *     dave.name     #=> "Dave"
+ *     dave.greeting #=> "Hello Dave!"
  *
- *  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.''
+ *  See Struct::new for further examples of creating struct subclasses and
+ *  instances.
  *
- *  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>).
+ *  In the method descriptions that follow a "member" parameter refers to a
+ *  struct member which is either a quoted string (<code>"name"</code>) or a
+ *  Symbol (<code>:name</code>).
  */
 void
 Init_Struct(void)