Enhanced RDoc for Struct (#4895)

    Revises introductory material.
    Adds section "What's Here".
    Adds previously missing documentation for method #deconstruct_keys.

1 files changed, 111 insertions, 18 deletions

diff --git a/struct.c b/struct.c
index 3bc2671e60..5aa70edf24 100644
--- a/struct.c
+++ b/struct.c
@@ -1076,6 +1076,23 @@ rb_struct_to_h(VALUE s)
     return h;
 }
 
+/*
+ *  call-seq:
+ *    deconstruct_keys(array_of_names) -> hash
+ *
+ *  Returns a hash of the name/value pairs for the given member names.
+ *
+ *    Customer = Struct.new(:name, :address, :zip)
+ *    joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
+ *    h = joe.deconstruct_keys([:zip, :address])
+ *    h # => {:zip=>12345, :address=>"123 Maple, Anytown NC"}
+ *
+ *  Returns all names and values if +array_of_names+ is +nil+:
+ *
+ *    h = joe.deconstruct_keys(nil)
+ *    h # => {:name=>"Joseph Smith, Jr.", :address=>"123 Maple, Anytown NC", :zip=>12345}
+ *
+ */
 static VALUE
 rb_struct_deconstruct_keys(VALUE s, VALUE keys)
 {
@@ -1544,29 +1561,105 @@ rb_struct_dig(int argc, VALUE *argv, VALUE self)
 /*
  *  Document-class: Struct
  *
- *  A Struct is a convenient way to bundle a number of attributes together,
- *  using accessor methods, without having to write an explicit class.
+ *  \Class \Struct provides a convenient way to create a simple class
+ *  that can store and fetch values.
+ *
+ *  This example creates a subclass of +Struct+, <tt>Struct::Customer</tt>;
+ *  the first argument, a string, is the name of the subclass;
+ *  the other arguments, symbols, determine the _members_ of the new subclass.
+ *
+ *    Customer = Struct.new('Customer', :name, :address, :zip)
+ *    Customer.name       # => "Struct::Customer"
+ *    Customer.class      # => Class
+ *    Customer.superclass # => Struct
+ *
+ *  Corresponding to each member are two methods, a writer and a reader,
+ *  that store and fetch values:
+ *
+ *    methods = Customer.instance_methods false
+ *    methods # => [:zip, :address=, :zip=, :address, :name, :name=]
+ *
+ *  An instance of the subclass may be created,
+ *  and its members assigned values, via method <tt>::new</tt>:
+ *
+ *    joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
+ *    joe # => #<struct Struct::Customer name="Joe Smith", address="123 Maple, Anytown NC", zip=12345>
+ *
+ *  The member values may be managed thus:
+ *
+ *    joe.name    # => "Joe Smith"
+ *    joe.name = 'Joseph Smith'
+ *    joe.name    # => "Joseph Smith"
+ *
+ *  And thus; note that member name may be expressed as either a string or a symbol:
+ *
+ *    joe[:name]  # => "Joseph Smith"
+ *    joe[:name] = 'Joseph Smith, Jr.'
+ *    joe['name'] # => "Joseph Smith, Jr."
+ *
+ *  See Struct::new.
+ *
+ *  == What's Here
+ *
+ *  First, what's elsewhere. \Class \Struct:
+ *
+ *  - Inherits from {class Object}[Object.html#class-Object-label-What-27s+Here].
+ *  - Includes {module Enumerable}[Enumerable.html#module-Enumerable-label-What-27s+Here],
+ *    which provides dozens of additional methods.
+ *
+ *  Here, class \Struct provides methods that are useful for:
+ *
+ *  - {Creating a Struct Subclass}[#class-Struct-label-Methods+for+Creating+a+Struct+Subclass]
+ *  - {Querying}[#class-Struct-label-Methods+for+Querying]
+ *  - {Comparing}[#class-Struct-label-Methods+for+Comparing]
+ *  - {Fetching}[#class-Struct-label-Methods+for+Fetching]
+ *  - {Assigning}[#class-Struct-label-Methods+for+Assigning]
+ *  - {Iterating}[#class-Struct-label-Methods+for+Iterating]
+ *  - {Converting}[#class-Struct-label-Methods+for+Converting]
+ *
+ *  === Methods for Creating a Struct Subclass
+ *
+ *  ::new:: Returns a new subclass of \Struct.
+ *
+ *  === Methods for Querying
+ *
+ *  #hash:: Returns the integer hash code.
+ *  #length, #size:: Returns the number of members.
+ *
+ *  === Methods for Comparing
+ *
+ *  {#==}[#method-i-3D-3D]:: Returns whether a given object is equal to +self+,
+ *                           using <tt>==</tt> to compare member values.
+ *  #eql?:: Returns whether a given object is equal to +self+,
+ *          using <tt>eql?</tt> to compare member values.
+ *
+ *  === Methods for Fetching
+ *
+ *  #[]:: Returns the value associated with a given member name.
+ *  #to_a, #values, #deconstruct:: Returns the member values in +self+ as an array.
+ *  #deconstruct_keys:: Returns a hash of the name/value pairs
+ *                      for given member names.
+ *  #dig:: Returns the object in nested objects that is specified
+ *         by a given member name and additional arguments.
+ *  #members:: Returns an array of the member names.
+ *  #select, #filter:: Returns an array of member values from +self+,
+ *                     as selected by the given block.
+ *  #values_at:: Returns an array containing values for given member names.
+ *
+ *  === Methods for Assigning
+ *
+ *  #[]=:: Assigns a given value to a given member name.
  *
- *  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.
+ *  === Methods for Iterating
  *
- *     Customer = Struct.new(:name, :address) do
- *       def greeting
- *         "Hello #{name}!"
- *       end
- *     end
+ *  #each:: Calls a given block with each member name.
+ *  #each_pair:: Calls a given block with each member name/value pair.
  *
- *     dave = Customer.new("Dave", "123 Main")
- *     dave.name     #=> "Dave"
- *     dave.greeting #=> "Hello Dave!"
+ *  === Methods for Converting
  *
- *  See Struct::new for further examples of creating struct subclasses and
- *  instances.
+ *  #inspect, #to_s:: Returns a string representation of +self+.
+ *  #to_h:: Returns a hash of the member name/value pairs in +self+.
  *
- *  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
 InitVM_Struct(void)