summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorstomar <stomar@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2017-03-01 19:59:03 +0000
committerstomar <stomar@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2017-03-01 19:59:03 +0000
commit745f4dd5b834a00f1cc201adb72ea3c8c8d4decb (patch)
tree7bd67087fd77444c126e663170668cc416ca8b69
parent9386e511b54d8bf7266766b952b95ee0b30dc504 (diff)
struct.c: improve rdoc for Struct
* struct.c: [DOC] improve examples for ::new, improve #dig example, simplify #select example, use consistent style for return values, fix typos and example code style, remove duplicate cross reference. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@57755 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
-rw-r--r--struct.c53
1 files changed, 30 insertions, 23 deletions
diff --git a/struct.c b/struct.c
index 745d280..f1f361f 100644
--- a/struct.c
+++ b/struct.c
@@ -436,10 +436,10 @@ rb_struct_define_under(VALUE outer, const char *name, ...)
/*
* call-seq:
- * Struct.new([class_name] [, member_name]+>) -> StructClass
- * Struct.new([class_name] [, member_name]+>) {|StructClass| block } -> StructClass
- * StructClass.new(value, ...) -> obj
- * StructClass[value, ...] -> obj
+ * Struct.new([class_name] [, member_name]+) -> StructClass
+ * Struct.new([class_name] [, member_name]+) {|StructClass| block } -> StructClass
+ * StructClass.new(value, ...) -> object
+ * StructClass[value, ...] -> object
*
* 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
@@ -457,6 +457,12 @@ rb_struct_define_under(VALUE outer, const char *name, ...)
* Struct::Customer.new("Dave", "123 Main")
* #=> #<struct 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")
+ * #=> #<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:
*
@@ -465,7 +471,7 @@ rb_struct_define_under(VALUE outer, const char *name, ...)
* "Hello #{name}!"
* end
* end
- * Customer.new("Dave", "123 Main").greeting # => "Hello Dave!"
+ * Customer.new("Dave", "123 Main").greeting #=> "Hello Dave!"
*
* This is the recommended way to customize a struct. Subclassing an
* anonymous struct creates an extra anonymous class that will never be used.
@@ -476,11 +482,11 @@ rb_struct_define_under(VALUE outer, const char *name, ...)
* Passing more parameters than number of attributes 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["Dave"]
+ * #=> #<struct Customer name="Dave", address=nil>
*/
static VALUE
@@ -625,7 +631,7 @@ struct_enum_size(VALUE s, VALUE args, VALUE eobj)
/*
* call-seq:
* struct.each {|obj| block } -> struct
- * struct.each -> an_enumerator
+ * struct.each -> enumerator
*
* Yields the value of each struct member in order. If no block is given an
* enumerator is returned.
@@ -656,7 +662,7 @@ rb_struct_each(VALUE s)
/*
* call-seq:
* struct.each_pair {|sym, obj| block } -> struct
- * struct.each_pair -> an_enumerator
+ * struct.each_pair -> enumerator
*
* Yields the name and value of each struct member in order. If no block is
* given an enumerator is returned.
@@ -747,7 +753,7 @@ inspect_struct(VALUE s, VALUE dummy, int recur)
* struct.to_s -> string
* struct.inspect -> string
*
- * Describe the contents of this struct in a string.
+ * Returns a description of this struct as a string.
*/
static VALUE
@@ -871,8 +877,8 @@ invalid_struct_pos(VALUE s, VALUE idx)
/*
* call-seq:
- * struct[member] -> anObject
- * struct[index] -> anObject
+ * struct[member] -> object
+ * struct[index] -> object
*
* Attribute Reference---Returns the value of the given struct +member+ or
* the member at the given +index+. Raises NameError if the +member+ does
@@ -948,7 +954,7 @@ struct_entry(VALUE s, long n)
/*
* call-seq:
- * struct.values_at(selector, ...) -> an_array
+ * struct.values_at(selector, ...) -> array
*
* 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
@@ -956,7 +962,7 @@ struct_entry(VALUE s, long n)
*
* Customer = Struct.new(:name, :address, :zip)
* joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
- * joe.values_at 0, 2 #=> ["Joe Smith", 12345]
+ * joe.values_at(0, 2) #=> ["Joe Smith", 12345]
*
*/
@@ -968,8 +974,8 @@ rb_struct_values_at(int argc, VALUE *argv, VALUE s)
/*
* call-seq:
- * struct.select {|i| block } -> array
- * struct.select -> an_enumerator
+ * struct.select {|obj| block } -> array
+ * struct.select -> enumerator
*
* 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
@@ -977,7 +983,7 @@ rb_struct_values_at(int argc, VALUE *argv, VALUE s)
*
* Lots = Struct.new(:a, :b, :c, :d, :e, :f)
* l = Lots.new(11, 22, 33, 44, 55, 66)
- * l.select {|v| (v % 2).zero? } #=> [22, 44, 66]
+ * l.select {|v| v.even? } #=> [22, 44, 66]
*/
static VALUE
@@ -1046,7 +1052,7 @@ rb_struct_equal(VALUE s, VALUE s2)
* call-seq:
* struct.hash -> integer
*
- * Returns a hash value based on this struct's contents (see Object#hash).
+ * Returns a hash value based on this struct's contents.
*
* See also Object#hash.
*/
@@ -1134,11 +1140,12 @@ rb_struct_size(VALUE s)
* objects by calling +dig+ at each step, returning +nil+ if any
* intermediate step is +nil+.
*
- * klass = Struct.new(:a)
- * o = klass.new(klass.new({b: [1, 2, 3]}))
+ * Foo = Struct.new(:a)
+ * f = Foo.new(Foo.new({b: [1, 2, 3]}))
*
- * o.dig(:a, :a, :b, 0) #=> 1
- * o.dig(:b, 0) #=> nil
+ * f.dig(:a, :a, :b, 0) # => 1
+ * f.dig(:b, 0) # => nil
+ * f.dig(:a, :a, :b, :c) # TypeError: no implicit conversion of Symbol into Integer
*/
static VALUE
@@ -1174,7 +1181,7 @@ rb_struct_dig(int argc, VALUE *argv, VALUE self)
* See Struct::new for further examples of creating struct subclasses and
* instances.
*
- * In the method descriptions that follow a "member" parameter refers to a
+ * 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>).
*/