[pull] master from ruby:master

set.c

@@ -801,10 +801,15 @@ set_i_delete(VALUE set, VALUE item)
 
 /*
  *  call-seq:
- *    delete?(obj) -> self or nil
+ *    delete?(object) -> self or nil
  *
- *  Deletes the given object from the set and returns self.  If the
- *  object is not in the set, returns nil.
+ *  Like #delete, but returns +nil+ if the object is not in +self+:
+ *
+ *    set = Set[0, 'zero', :zero]
+ *    set.delete?(0) # => Set["zero", :zero]
+ *    set.delete?(0) # => nil
+ *
+ *  Related: see {Methods for Deleting}[rdoc-ref:Set@Methods+for+Deleting].
  */
 static VALUE
 set_i_delete_p(VALUE set, VALUE item)
@@ -825,11 +830,20 @@ set_delete_if_i(st_data_t key, st_data_t dummy)
 
 /*
  *  call-seq:
- *    delete_if { |o| ... } -> self
+ *    delete_if {|element| ... } -> self
  *    delete_if -> enumerator
  *
- *  Deletes every element of the set for which block evaluates to
- *  true, and returns self. Returns an enumerator if no block is given.
+ *  With a block given, calls the block with each element in +self+;
+ *  removes the element if the block returns a truthy value:
+ *
+ *    set = Set[*0..9]
+ *    # => Set[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+ *    set.delete_if {|element| element.even? }
+ *    # => Set[1, 3, 5, 7, 9]
+ *
+ *  With no block given, returns an Enumerator.
+ *
+ *  Related: {Methods for Deleting}[rdoc-ref:Set@Methods+for+Deleting].
  */
 static VALUE
 set_i_delete_if(VALUE set)
@@ -1819,15 +1833,15 @@ set_i_intersect(VALUE set, VALUE other)
 
 /*
  *  call-seq:
- *    disjoint?(set) -> true or false
+ *    disjoint?(enumerable) -> true or false
  *
- *  Returns true if the set and the given enumerable have no
- *  element in common.  This method is the opposite of +intersect?+.
+ *  Returns whether no element of +enumerable+ is present in +self+:
+ *
+ *    set = Set[0, 'zero', :zero]
+ *    set.disjoint?([1, 2, 3])    # => true
+ *    set.disjoint?([0, 1, 2, 3]) # => false
  *
- *    Set[1, 2, 3].disjoint? Set[3, 4]   #=> false
- *    Set[1, 2, 3].disjoint? Set[4, 5]   #=> true
- *    Set[1, 2, 3].disjoint? [3, 4]      #=> false
- *    Set[1, 2, 3].disjoint? 4..5        #=> true
+ *  Related: see {Methods for Querying}[rdoc-ref:Set@Methods+for+Querying].
  */
 static VALUE
 set_i_disjoint(VALUE set, VALUE other)