Fixed example codes (semantics)

Author: maiha

src/array.cr

@@ -31,7 +31,7 @@
 # `new` method and a `<<` method. `Set` is one such type:
 #
 # ```
-# set = Set{1, 2, 3} # => [1, 2, 3]
+# set = Set{1, 2, 3} # => Set{1, 2, 3}
 # set.class          # => Set(Int32)
 # ```
 #
@@ -313,7 +313,7 @@ class Array(T)
   # ary[0] = 5
   # p ary # => [5,2,3]
   #
-  # ary[3] = 5 # => IndexError
+  # ary[3] = 5 # raises IndexError
   # ```
   @[AlwaysInline]
   def []=(index : Int, value : T)
@@ -449,7 +449,7 @@ class Array(T)
   # a = ["a", "b", "c", "d", "e"]
   # a[1..3]    # => ["b", "c", "d"]
   # a[4..7]    # => ["e"]
-  # a[6..10]   # => Index Error
+  # a[6..10]   # raise IndexError
   # a[5..10]   # => []
   # a[-2...-1] # => ["d"]
   # ```
@@ -469,7 +469,7 @@ class Array(T)
   # ```
   # a = ["a", "b", "c", "d", "e"]
   # a[-3, 3] # => ["c", "d", "e"]
-  # a[6, 1]  # => Index Error
+  # a[6, 1]  # raise IndexError
   # a[1, 2]  # => ["b", "c"]
   # a[5, 1]  # => []
   # ```
@@ -618,7 +618,7 @@ class Array(T)
   # a = ["ant", "bat", "cat", "dog"]
   # a.delete_at(2)  # => "cat"
   # a               # => ["ant", "bat", "dog"]
-  # a.delete_at(99) # => IndexError
+  # a.delete_at(99) # raises IndexError
   # ```
   def delete_at(index : Int)
     index = check_index_out_of_bounds index
@@ -638,7 +638,7 @@ class Array(T)
   # a = ["ant", "bat", "cat", "dog"]
   # a.delete_at(1..2)    # => ["bat", "cat"]
   # a                    # => ["ant", "dog"]
-  # a.delete_at(99..100) # => IndexError
+  # a.delete_at(99..100) # raises IndexError
   # ```
   def delete_at(range : Range(Int, Int))
     from, size = range_to_index_and_count(range)
@@ -654,7 +654,7 @@ class Array(T)
   # a = ["ant", "bat", "cat", "dog"]
   # a.delete_at(1, 2)  # => ["bat", "cat"]
   # a                  # => ["ant", "dog"]
-  # a.delete_at(99, 1) # => IndexError
+  # a.delete_at(99, 1) # raises IndexError
   # ```
   def delete_at(index : Int, count : Int)
     val = self[index, count]
@@ -1014,7 +1014,7 @@ class Array(T)
   # iter.next # => [2, 3, 1]
   # iter.next # => [3, 1, 2]
   # iter.next # => [3, 2, 1]
-  # iter.next # => Iterator::Stop
+  # iter.next # => #<Iterator::Stop>
   # ```
   #
   # By default, a new array is created and returned for each permutation.
@@ -1109,8 +1109,8 @@ class Array(T)
   # ```
   # s = [1, 2, 3]          # => [1, 2, 3]
   # t = [4, 5, 6, [7, 8]]  # => [4, 5, 6, [7, 8]]
-  # u = [9, [10, 11].each] # => [9, Indexable#ItemIterator]
-  # a = [s, t, u, 12, 13]  # => [[1, 2, 3], [4, 5, 6, [7, 8]], 9, 10]
+  # u = [9, [10, 11].each] # => [9, #<Indexable::ItemIterator>]
+  # a = [s, t, u, 12, 13]  # => [[1, 2, 3], [4, 5, 6, [7, 8]], 9, #<Indexable::ItemIterator>, 12, 13]
   # a.flatten              # => [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13]
   # ```
   def flatten
@@ -1325,7 +1325,7 @@ class Array(T)
   # ```
   # a = ["a", "b"]
   # a.push("c") # => ["a", "b", "c"]
-  # a.push(1)   # => Errors, because the array only accepts String.
+  # a.push(1)   # Errors, because the array only accepts String.
   #
   # a = ["a", "b"] of (Int32 | String)
   # a.push("c") # => ["a", "b", "c"]
@@ -1714,12 +1714,12 @@ class Array(T)
   #
   # ```
   # a = ["a", "b"]
-  # a.unshift("c") # => ["c", a", "b"]
-  # a.unshift(1)   # => Errors, because the array only accepts String.
+  # a.unshift("c") # => ["c", "a", "b"]
+  # a.unshift(1)   # Errors, because the array only accepts String.
   #
   # a = ["a", "b"] of (Int32 | String)
   # a.unshift("c") # => ["c", "a", "b"]
-  # a.unshift(1)   # => [1, "a", "b", "c"]
+  # a.unshift(1)   # => [1, "c", "a", "b"]
   # ```
   def unshift(obj : T)
     insert 0, obj

src/atomic.cr

@@ -104,8 +104,8 @@ struct Atomic(T)
   #
   # ```
   # atomic = Atomic.new(5)
-  # atomic.or(3) # => 5
-  # atomic.get   # => 6
+  # atomic.xor(3) # => 5
+  # atomic.get    # => 6
   # ```
   def xor(value : T)
     Ops.atomicrmw(:xor, pointerof(@value), value, :sequentially_consistent, false)
@@ -153,8 +153,8 @@ struct Atomic(T)
   #
   # ```
   # atomic = Atomic.new(5)
-  # atomic.set(10) # => 5
-  # atomic.get     # => 10
+  # atomic.swap(10) # => 5
+  # atomic.get      # => 10
   # ```
   def swap(value : T)
     Ops.atomicrmw(:xchg, pointerof(@value), value, :sequentially_consistent, false)

src/base64.cr

@@ -10,7 +10,7 @@
 # require "base64"
 #
 # enc = Base64.encode("Send reinforcements") # => "U2VuZCByZWluZm9yY2VtZW50cw==\n"
-# plain = Base64.decode(enc)                 # => "Send reinforcements"
+# plain = Base64.decode_string(enc)          # => "Send reinforcements"
 # ```
 #
 # The purpose of using base64 to encode data is that it translates any binary
@@ -32,15 +32,14 @@ module Base64
   # Line feeds are added to every 60 encoded characters.
   #
   # ```
-  # require "base64"
-  #
   # puts Base64.encode("Now is the time for all good coders\nto learn Crystal")
   # ```
   #
   # Generates:
   #
   # ```text
   # Tm93IGlzIHRoZSB0aW1lIGZvciBhbGwgZ29vZCBjb2RlcnMKdG8gbGVhcm4g
+  # Q3J5c3RhbA==
   # ```
   def encode(data) : String
     slice = data.to_slice
@@ -57,9 +56,7 @@ module Base64
   # Line feeds are added to every 60 encoded characters.
   #
   # ```
-  # require "base64"
-  #
-  # Base64.encode("Now is the time for all good coders\nto learn Crystal", io)
+  # Base64.encode("Now is the time for all good coders\nto learn Crystal", STDOUT)
   # ```
   def encode(data, io : IO)
     count = 0
@@ -90,8 +87,6 @@ module Base64
   # This method complies with RFC 4648.
   #
   # ```
-  # require "base64"
-  #
   # puts Base64.strict_encode("Now is the time for all good coders\nto learn Crystal")
   # ```
   #
@@ -118,9 +113,7 @@ module Base64
   # This method complies with RFC 4648.
   #
   # ```
-  # require "base64"
-  #
-  # Base64.strict_encode("Now is the time for all good coders\nto learn Crystal", io)
+  # Base64.strict_encode("Now is the time for all good coders\nto learn Crystal", STDOUT)
   # ```
   def strict_encode(data, io : IO)
     strict_encode_to_io_internal(data, io, CHARS_STD, pad: true)

src/benchmark.cr

@@ -27,7 +27,7 @@ require "./benchmark/**"
 #
 # ```
 # Benchmark.ips(warmup: 4, calculation: 10) do |x|
-#   # …
+#   x.report("sleep") { sleep 0.01 }
 # end
 # ```
 #

src/big/big_rational.cr

@@ -6,6 +6,8 @@ require "./big"
 # denominator is positive. Zero has the unique representation 0/1.
 #
 # ```
+# require "big_rational"
+#
 # r = BigRational.new(BigInt.new(7), BigInt.new(3))
 # r.to_s # => "7/3"
 #

src/char.cr

@@ -157,7 +157,7 @@ struct Char
   #
   # ```
   # 'c'.ascii_lowercase? # => true
-  # 'ç'.lowercase?       # => false
+  # 'ç'.lowercase?       # => true
   # 'G'.ascii_lowercase? # => false
   # '.'.ascii_lowercase? # => false
   # ```
@@ -479,9 +479,9 @@ struct Char
   #
   # ```
   # 'a'.inspect      # => "'a'"
-  # '\t'.inspect     # => "'\t'"
+  # '\t'.inspect     # => "'\\t'"
   # 'あ'.inspect      # => "'あ'"
-  # '\u0012'.inspect # => "'\u{12}'"
+  # '\u0012'.inspect # => "'\\u{12}'"
   # ```
   def inspect
     dump_or_inspect do |io|
@@ -507,9 +507,9 @@ struct Char
   #
   # ```
   # 'a'.dump      # => "'a'"
-  # '\t'.dump     # => "'\t'"
-  # 'あ'.dump      # => "'\u{3042}'"
-  # '\u0012'.dump # => "'\u{12}'"
+  # '\t'.dump     # => "'\\t'"
+  # 'あ'.dump      # => "'\\u{3042}'"
+  # '\u0012'.dump # => "'\\u{12}'"
   # ```
   def dump
     dump_or_inspect do |io|
@@ -557,11 +557,11 @@ struct Char
   # ```
   # '1'.to_i     # => 1
   # '8'.to_i     # => 8
-  # 'c'.to_i     # => ArgumentError
+  # 'c'.to_i     # raises ArgumentError
   # '1'.to_i(16) # => 1
   # 'a'.to_i(16) # => 10
   # 'f'.to_i(16) # => 15
-  # 'z'.to_i(16) # => ArgumentError
+  # 'z'.to_i(16) # raises ArgumentError
   # ```
   def to_i(base : Int = 10) : Int32
     to_i?(base) || raise ArgumentError.new("Invalid integer: #{self}")
@@ -573,11 +573,11 @@ struct Char
   # ```
   # '1'.to_i     # => 1
   # '8'.to_i     # => 8
-  # 'c'.to_i     # => ArgumentError
+  # 'c'.to_i     # raises ArgumentError
   # '1'.to_i(16) # => 1
   # 'a'.to_i(16) # => 10
   # 'f'.to_i(16) # => 15
-  # 'z'.to_i(16) # => ArgumentError
+  # 'z'.to_i(16) # raises ArgumentError
   # ```
   def to_i?(base : Int = 10) : Int32?
     raise ArgumentError.new "invalid base #{base}, expected 2 to 36" unless 2 <= base <= 36
@@ -623,7 +623,7 @@ struct Char
   # ```
   # '1'.to_i # => 1.0
   # '8'.to_i # => 8.0
-  # 'c'.to_i # => ArgumentError
+  # 'c'.to_i # raises ArgumentError
   # ```
   def to_f
     to_f64
@@ -635,7 +635,7 @@ struct Char
   # ```
   # '1'.to_i # => 1.0
   # '8'.to_i # => 8.0
-  # 'c'.to_i # => ArgumentError
+  # 'c'.to_i # raises ArgumentError
   # ```
   def to_f?
     to_f64?

src/complex.cr

@@ -6,8 +6,8 @@
 # ```
 # require "complex"
 #
-# Complex.new(1, 0)   # => 1 + 0i
-# Complex.new(5, -12) #  => 5 - 12i
+# Complex.new(1, 0)   # => 1.0 + 0.0i
+# Complex.new(5, -12) # => 5.0 - 12.0i
 # ```
 struct Complex
   #  Returns the real part of self
@@ -39,7 +39,7 @@ struct Complex
   # Write this complex object to an io
   #
   # ```
-  # Complex.new(42, 2).to_s # => 42 + 2i
+  # Complex.new(42, 2).to_s # => "42.0 + 2.0i"
   # ```
   def to_s(io : IO)
     io << @real
@@ -51,7 +51,7 @@ struct Complex
   # Write this complex object to an io, surrounded by parentheses.
   #
   # ```
-  # Complex.new(42, 2).inspect # => (42 + 2i)
+  # Complex.new(42, 2).inspect # => "(42.0 + 2.0i)"
   # ```
   def inspect(io : IO)
     io << '('
@@ -63,8 +63,8 @@ struct Complex
   # number form, using the Pythagorean theorem.
   #
   # ```
-  # Complex.new(42, 2).abs  # => 42.0476
-  # Complex.new(-42, 2).abs # => 42.0476
+  # Complex.new(42, 2).abs  # => 42.047592083257278
+  # Complex.new(-42, 2).abs # => 42.047592083257278
   # ```
   def abs
     Math.hypot(@real, @imag)
@@ -91,7 +91,7 @@ struct Complex
   # Returns a tuple with the abs value and the phase.
   #
   # ```
-  # Complex.new(42, 2).polar # => {2.54311, 0.665774}
+  # Complex.new(42, 2).polar # => {42.047592083257278, 0.047583103276983396}
   # ```
   def polar
     {abs, phase}
@@ -100,8 +100,8 @@ struct Complex
   # Returns the conjugate of self
   #
   # ```
-  # Complex.new(42, 2).conj  # => 42 - 2i
-  # Complex.new(42, -2).conj # => 42 + 2i
+  # Complex.new(42, 2).conj  # => 42.0 - 2.0i
+  # Complex.new(42, -2).conj # => 42.0 + 2.0i
   # ```
   def conj
     Complex.new(@real, -@imag)
@@ -139,7 +139,7 @@ struct Complex
   # Calculates the exp of self
   #
   # ```
-  # Complex.new(4, 2).exp #  => -22.7208 + 49.646i
+  # Complex.new(4, 2).exp # => -22.720847417619233 + 49.645957334580565i
   # ```
   def exp
     r = Math.exp(@real)

src/concurrent/future.cr

@@ -120,8 +120,8 @@ end
 # Access to get is synchronized between fibers.  *&block* is only called once.
 # May be canceled before *&block* is called by calling `cancel`.
 # ```
-# d = delay(1) { Process.kill(Process.pid) }
-# long_operation
+# d = delay(1) { Process.kill(Signal::KILL, Process.pid) }
+# # ... long operations ...
 # d.cancel
 # ```
 def delay(delay, &block : -> _)
@@ -131,9 +131,9 @@ end
 # Spawns a `Fiber` to compute *&block* in the background.
 # Access to get is synchronized between fibers.  *&block* is only called once.
 # ```
-# f = future { http_request }
-# ... other actions ...
-# f.get #=> String
+# f = future { `echo hello` }
+# # ... other actions ...
+# f.get # => "hello\n"
 # ```
 def future(&exp : -> _)
   Concurrent::Future.new &exp

src/crypto/bcrypt/password.cr

@@ -35,8 +35,8 @@ class Crypto::Bcrypt::Password
   # ```
   # password = Crypto::Bcrypt::Password.new("$2a$10$X6rw/jDiLBuzHV./JjBNXe8/Po4wTL0fhdDNdAdjcKN/Fup8tGCya")
   # password.version # => "2a"
-  # password.salt    # => X6rw/jDiLBuzHV./JjBNXe
-  # password.digest  # => 8/Po4wTL0fhdDNdAdjcKN/Fup8tGCya
+  # password.salt    # => "X6rw/jDiLBuzHV./JjBNXe"
+  # password.digest  # => "8/Po4wTL0fhdDNdAdjcKN/Fup8tGCya"
   # ```
   def initialize(@raw_hash : String)
     parts = @raw_hash.split("$")