set.rb: improve docs for Set

* lib/set.rb: [DOC] add examples for Set#replace,
  add examples for creating a set from a hash with duplicates,
  simplify and fix style of some other examples, fix typos.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@60879 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

lib/set.rb

@@ -47,15 +47,15 @@
 #
 # == Comparison
 #
-# The comparison operators <, >, <= and >= are implemented as
+# The comparison operators <, >, <=, and >= are implemented as
 # shorthand for the {proper_,}{subset?,superset?} methods.  However,
 # the <=> operator is intentionally left out because not every pair of
-# sets is comparable. ({x,y} vs. {x,z} for example)
+# sets is comparable ({x, y} vs. {x, z} for example).
 #
 # == Example
 #
 #   require 'set'
-#   s1 = Set.new([1, 2])                  #=> #<Set: {1, 2}>
+#   s1 = Set[1, 2]                        #=> #<Set: {1, 2}>
 #   s2 = [1, 2].to_set                    #=> #<Set: {1, 2}>
 #   s1 == s2                              #=> true
 #   s1.add("foo")                         #=> #<Set: {1, 2, "foo"}>
@@ -73,6 +73,7 @@ class Set
   # Creates a new set containing the given objects.
   #
   #     Set[1, 2]                   # => #<Set: {1, 2}>
+  #     Set[1, 2, 1]                # => #<Set: {1, 2}>
   #     Set[1, 'c', :s]             # => #<Set: {1, "c", :s}>
   def self.[](*ary)
     new(ary)
@@ -85,8 +86,9 @@ class Set
   # given block.
   #
   #     Set.new([1, 2])                       #=> #<Set: {1, 2}>
+  #     Set.new([1, 2, 1])                    #=> #<Set: {1, 2}>
   #     Set.new([1, 'c', :s])                 #=> #<Set: {1, "c", :s}>
-  #     Set.new((1..10))   #=> #<Set: {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}>
+  #     Set.new(1..5)                         #=> #<Set: {1, 2, 3, 4, 5}>
   #     Set.new([1, 2, 3]) { |x| x * x }      #=> #<Set: {1, 4, 9}>
   def initialize(enum = nil, &block) # :yields: o
     @hash ||= Hash.new(false)
@@ -178,6 +180,10 @@ class Set
 
   # Replaces the contents of the set with the contents of the given
   # enumerable object and returns self.
+  #
+  #     set = Set[1, 'c', :s]             #=> #<Set: {1, "c", :s}>
+  #     set.replace([1, 2])               #=> #<Set: {1, 2}>
+  #     set                               #=> #<Set: {1, 2}>
   def replace(enum)
     if enum.instance_of?(self.class)
       @hash.replace(enum.instance_variable_get(:@hash))
@@ -304,9 +310,6 @@ class Set
   # Returns true if the set and the given set have at least one
   # element in common.
   #
-  # e.g.:
-  #
-  #   require 'set'
   #   Set[1, 2, 3].intersect? Set[4, 5]   #=> false
   #   Set[1, 2, 3].intersect? Set[3, 4]   #=> true
   def intersect?(set)
@@ -321,12 +324,8 @@ class Set
   # Returns true if the set and the given set have no element in
   # common.  This method is the opposite of +intersect?+.
   #
-  # e.g.:
-  #
-  #   require 'set'
   #   Set[1, 2, 3].disjoint? Set[3, 4]   #=> false
   #   Set[1, 2, 3].disjoint? Set[4, 5]   #=> true
-
   def disjoint?(set)
     !intersect?(set)
   end
@@ -447,7 +446,7 @@ class Set
   # Returns a new set built by merging the set and the elements of the
   # given enumerable object.
   #
-  #     Set[1, 2, 3, 3] | Set[2, 4, 5]      #=> #<Set: {1, 2, 3, 4, 5}>
+  #     Set[1, 2, 3] | Set[2, 4, 5]         #=> #<Set: {1, 2, 3, 4, 5}>
   #     Set[1, 5, 'z'] | (1..6)             #=> #<Set: {1, 5, "z", 2, 3, 4, 6}>
   def |(enum)
     dup.merge(enum)
@@ -557,12 +556,10 @@ class Set
   # called once for each element of the set, passing the element as
   # parameter.
   #
-  # e.g.:
-  #
   #   require 'set'
   #   files = Set.new(Dir.glob("*.rb"))
   #   hash = files.classify { |f| File.mtime(f).year }
-  #   p hash    # => {2000=>#<Set: {"a.rb", "b.rb"}>,
+  #   hash       #=> {2000=>#<Set: {"a.rb", "b.rb"}>,
   #              #    2001=>#<Set: {"c.rb", "d.rb", "e.rb"}>,
   #              #    2002=>#<Set: {"f.rb"}>}
   #
@@ -586,12 +583,10 @@ class Set
   # if block.call(o1, o2) is true.  Otherwise, elements o1 and o2 are
   # in common if block.call(o1) == block.call(o2).
   #
-  # e.g.:
-  #
   #   require 'set'
   #   numbers = Set[1, 3, 4, 6, 9, 10, 11]
   #   set = numbers.divide { |i,j| (i - j).abs == 1 }
-  #   p set     # => #<Set: {#<Set: {1}>,
+  #   set        #=> #<Set: {#<Set: {1}>,
   #              #           #<Set: {11, 9, 10}>,
   #              #           #<Set: {3, 4}>,
   #              #           #<Set: {6}>}>
@@ -630,7 +625,7 @@ class Set
   InspectKey = :__inspect_key__         # :nodoc:
 
   # Returns a string containing a human-readable representation of the
-  # set. ("#<Set: {element1, element2, ...}>")
+  # set ("#<Set: {element1, element2, ...}>").
   def inspect
     ids = (Thread.current[InspectKey] ||= [])