[pull] master from ruby:master

set.c

@@ -778,10 +778,16 @@ set_i_add_p(VALUE set, VALUE item)
 
 /*
  *  call-seq:
- *    delete(obj) -> self
+ *    delete(object) -> self
  *
- *  Deletes the given object from the set and returns self. Use subtract
- *  to delete many items at once.
+ *  Removes the given +object+ from +self+, if +self+ includes the object;
+ *  returns +self+:
+ *
+ *    set = Set[0, 'zero', :zero]
+ *    set.delete(0)       # => Set["zero", :zero]
+ *    set.delete(:nosuch) # => Set["zero", :zero]
+ *
+ *  Related: see {Methods for Deleting}[rdoc-ref:Set@Methods+for+Deleting].
  */
 static VALUE
 set_i_delete(VALUE set, VALUE item)
@@ -1024,11 +1030,11 @@ set_clear_i(st_data_t key, st_data_t dummy)
  *  call-seq:
  *    clear -> self
  *
- *  Removes all elements and returns self.
+ *  Returns +self+ with all elements removed:
  *
- *    set = Set[1, 'c', :s]             #=> Set[1, "c", :s]
- *    set.clear                         #=> Set[]
- *    set                               #=> Set[]
+ *    Set[1, :one, 'one', 1.0].clear # => Set[]
+ *
+ *  Related: see {Methods for Deleting}[rdoc-ref:Set@Methods+for+Deleting].
  */
 static VALUE
 set_i_clear(VALUE set)
@@ -1474,11 +1480,18 @@ set_collect_i(st_data_t key, st_data_t data)
 
 /*
  *  call-seq:
- *    collect! { |o| ... } -> self
+ *    collect! {|element| ... } -> self
  *    collect! -> enumerator
  *
- *  Replaces the elements with ones returned by +collect+.
- *  Returns an enumerator if no block is given.
+ *  With a block given, calls the block with each element in +self+;
+ *  replaces the element with the block's return value:
+ *
+ *    Set[1, :one, 'one', 1.0].collect! {|element| element.class }
+ *    # => Set[Integer, Symbol, String, Float]
+ *
+ *  With no block given, returns an Enumerator.
+ *
+ *  Related: see {Methods for Converting}[rdoc-ref:Set@Methods+for+Converting].
  */
 static VALUE
 set_i_collect(VALUE set)