From 745f4dd5b834a00f1cc201adb72ea3c8c8d4decb Mon Sep 17 00:00:00 2001 From: stomar Date: Wed, 1 Mar 2017 19:59:03 +0000 Subject: 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 --- struct.c | 53 ++++++++++++++++++++++++++++++----------------------- 1 file changed, 30 insertions(+), 23 deletions(-) diff --git a/struct.c b/struct.c index 745d2800ed..f1f361f953 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") * #=> # * + * # Create a structure named by its constant + * Customer = Struct.new(:name, :address) + * #=> Customer + * Customer.new("Dave", "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") * #=> # + * Customer["Dave"] + * #=> # */ 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 ("name") or a * Symbol (:name). */ -- cgit v1.2.3