Fixed example codes (syntax)

src/array.cr

@@ -1205,8 +1205,9 @@ class Array(T)
   #
   # ```
   # a = [1]
-  # a.pop { "Testing" } #=> 1
-  # a.pop { "Testing" } #=> "Testing"
+  # a.pop { "Testing" } # => 1
+  # a.pop { "Testing" } # => "Testing"
+  # ```
   def pop
     if @size == 0
       yield
@@ -1289,7 +1290,7 @@ class Array(T)
   #
   # ```
   # a = ["a"]
-  # a.push(["b", "c"]) # => ["a", "b", "c"]
+  # a.push("b", "c") # => ["a", "b", "c"]
   # ```
   def push(*values : T)
     new_size = @size + values.size

src/big/big_int.cr

@@ -13,6 +13,7 @@ struct BigInt < Int
   # Creates a BigInt with the value zero.
   #
   # ```
+  # require "big"
   # BigInt.new # => 0
   # ```
   def initialize

src/compiler/crystal/macros.cr

@@ -118,6 +118,7 @@ module Crystal::Macros
     # end
     #
     # puts test # prints "foo" (including the double quotes)
+    # ```
     def stringify : StringLiteral
     end
 

src/complex.cr

@@ -4,6 +4,7 @@
 #  the number.
 #
 # ```
+# require "complex"
 # Complex.new(1, 0)   # => 1 + 0i
 # Complex.new(5, -12) #  => 5 - 12i
 # ```

src/crypto/bcrypt/password.cr

@@ -4,6 +4,8 @@ require "../subtle"
 # Generate, read and verify `Crypto::Bcrypt` hashes.
 #
 # ```
+# require "crypto/bcrypt/password"
+#
 # password = Crypto::Bcrypt::Password.create("super secret", cost: 10)
 # # => $2a$10$rI4xRiuAN2fyiKwynO6PPuorfuoM4L2PVv6hlnVJEmNLjqcibAfHq
 #

src/crypto/subtle.cr

@@ -3,8 +3,9 @@ module Crypto::Subtle
   # Note: *x* and *y* must be able to respond to `to_slice`.
   #
   # ```
-  # Crypto::Suble.constant_time_compare("foo","bar") => false
-  # Crypto::Suble.constant_time_compare("foo","foo") => true
+  # require "crypto/subtle"
+  # Crypto::Subtle.constant_time_compare("foo", "bar") # => false
+  # Crypto::Subtle.constant_time_compare("foo", "foo") # => true
   # ```
   def self.constant_time_compare(x, y) : Bool
     x = x.to_slice

src/csv/builder.cr

@@ -3,6 +3,8 @@ require "./csv"
 # A CSV Builder writes CSV to an IO.
 #
 # ```
+# require "csv"
+#
 # result = CSV.build do |csv|
 #   # A row can be written by specifying several values
 #   csv.row "Hello", 1, 'a', "String with \"quotes\""

src/csv/lexer.cr

@@ -4,6 +4,7 @@ require "./csv"
 # parse a CSV without the need to allocate intermediate arrays.
 #
 # ```
+# require "csv"
 # lexer = CSV::Lexer.new "one,two\nthree"
 # lexer.next_token # => CSV::Token(@kind=Cell, @value="one")
 # lexer.next_token # => CSV::Token(@kind=Cell, @value="two")

src/deque.cr

@@ -74,7 +74,7 @@ class Deque(T)
   # value in that index.
   #
   # ```
-  # Deque.new(3) { |i| (i + 1) ** 2 } # => Deque{1, 4, 9}
+  # Deque(Int32).new(3) { |i| (i + 1) ** 2 } # => Deque{1, 4, 9}
   # ```
   def initialize(size : Int, &block : Int32 -> T)
     if size < 0
@@ -278,7 +278,7 @@ class Deque(T)
   #
   # ```
   # a = Deque{0, 1, 2}
-  # a.insert_at(1, 7) # => Deque{0, 7, 1, 2}
+  # a.insert(1, 7) # => Deque{0, 7, 1, 2}
   # ```
   def insert(index : Int, value : T)
     if index < 0

src/ecr/macros.cr

@@ -11,7 +11,7 @@ module ECR
   # require "ecr/macros"
   #
   # class Greeting
-  #   def initialize(@name)
+  #   def initialize(@name : String)
   #   end
   #
   #   ECR.def_to_s "greeting.ecr"

src/file_utils.cr

@@ -4,6 +4,7 @@ module FileUtils
   # Changes the current working directory of the process to the given string *path*.
   # Alias of Dir.cd.
   # ```
+  # require "file_utils"
   # FileUtils.cd("to/directory")
   # ```
   def cd(path : String)
@@ -273,6 +274,7 @@ module FileUtils
   # Removes all directories at the given *paths*.
   # ```
   # FileUtils.rmdir(["dir1", "dir2", "dir3"])
+  # ```
   def rmdir(paths : Enumerable(String)) : Nil
     paths.each do |path|
       Dir.rmdir(path)

src/hash.cr

@@ -306,13 +306,8 @@ class Hash(K, V)
   # hsh = {"foo" => "bar", "baz" => "qux"}
   # iterator = hsh.each
   #
-  # entry = iterator.next
-  # entry[0] # => "foo"
-  # entry[1] # => "bar"
-  #
-  # entry = iterator.next
-  # entry[0] # => "baz"
-  # entry[1] # => "qux"
+  # iterator.next # => {"foo", "bar"}
+  # iterator.next # => {"baz", "qux"}
   # ```
   def each
     EntryIterator(K, V).new(self, @first)

src/http/client.cr

@@ -416,7 +416,7 @@ class HTTP::Client
   #
   # ```
   # client = HTTP::Client.new "www.example.com"
-  # response = client.post_form "/", {"foo": "bar"}
+  # response = client.post_form "/", {"foo" => "bar"}
   # ```
   def post_form(path, form : Hash, headers : HTTP::Headers? = nil) : HTTP::Client::Response
     body = HTTP::Params.from_hash(form)
@@ -429,7 +429,7 @@ class HTTP::Client
   #
   # ```
   # client = HTTP::Client.new "www.example.com"
-  # client.post_form("/", {"foo": "bar"}) do |response|
+  # client.post_form("/", {"foo" => "bar"}) do |response|
   #   response.body_io.gets
   # end
   # ```

src/http/cookie.cr

@@ -209,7 +209,8 @@ module HTTP
     # Returns `true` if a cookie with the given *key* exists.
     #
     # ```
-    # request.cookies.has_key?("foo") #=> true
+    # request.cookies.has_key?("foo") # => true
+    # ```
     def has_key?(key)
       @cookies.has_key?(key)
     end

src/http/web_socket.cr

@@ -18,9 +18,9 @@ class HTTP::WebSocket
   # apart from `wss` and `https` will be treated as the default which is `ws`.
   #
   # ```
-  # WebSocket.new(URI.parse("ws://websocket.example.com/chat"))        # Creates a new WebSocket to `websocket.example.com`
-  # WebSocket.new(URI.parse("wss://websocket.example.com/chat"))       # Creates a new WebSocket with TLS to `websocket.example.com`
-  # WebSocket.new(URI.parse("http://websocket.example.com:8080/chat")) # Creates a new WebSocket to `websocket.example.com` on port `8080`
+  # HTTP::WebSocket.new(URI.parse("ws://websocket.example.com/chat"))        # Creates a new WebSocket to `websocket.example.com`
+  # HTTP::WebSocket.new(URI.parse("wss://websocket.example.com/chat"))       # Creates a new WebSocket with TLS to `websocket.example.com`
+  # HTTP::WebSocket.new(URI.parse("http://websocket.example.com:8080/chat")) # Creates a new WebSocket to `websocket.example.com` on port `8080`
   # ```
   def self.new(uri : URI | String)
     new(Protocol.new(uri))
@@ -30,8 +30,8 @@ class HTTP::WebSocket
   # and will raise an exception if the handshake did not complete successfully.
   #
   # ```
-  # WebSocket.new("websocket.example.com", "/chat")            # Creates a new WebSocket to `websocket.example.com`
-  # WebSocket.new("websocket.example.com", "/chat", tls: true) # Creates a new WebSocket with TLS to `ẁebsocket.example.com`
+  # HTTP::WebSocket.new("websocket.example.com", "/chat")            # Creates a new WebSocket to `websocket.example.com`
+  # HTTP::WebSocket.new("websocket.example.com", "/chat", tls: true) # Creates a new WebSocket with TLS to `ẁebsocket.example.com`
   # ```
   def self.new(host : String, path : String, port = nil, tls = false)
     new(Protocol.new(host, path, port, tls))

src/io.cr

@@ -29,7 +29,7 @@ require "c/unistd"
 #   def read(slice : Bytes)
 #     slice.size.times { |i| slice[i] = @slice[i] }
 #     @slice += slice.size
-#     count
+#     slice.size
 #   end
 #
 #   def write(slice : Bytes)
@@ -176,7 +176,8 @@ module IO
   # io = IO::Memory.new
   # slice = Bytes.new(4) { |i| ('a'.ord + i).to_u8 }
   # io.write(slice)
-  # io.to_s #=> "abcd"
+  # io.to_s # => "abcd"
+  # ```
   abstract def write(slice : Bytes) : Nil
 
   # Closes this IO.
@@ -494,7 +495,7 @@ module IO
   # slice = Bytes.new(5)
   # io.read_fully(slice) # => 5
   # slice                # => [49, 50, 51, 52, 53]
-  # io.read_fully        # => EOFError
+  # io.read_fully(slice) # => EOFError
   # ```
   def read_fully(slice : Bytes)
     read_fully?(slice) || raise(EOFError.new)
@@ -509,7 +510,7 @@ module IO
   # slice = Bytes.new(5)
   # io.read_fully?(slice) # => 5
   # slice                 # => [49, 50, 51, 52, 53]
-  # io.read_fully?        # => nil
+  # io.read_fully?(slice) # => nil
   # ```
   def read_fully?(slice : Bytes)
     count = slice.size

src/io/hexdump.cr

@@ -14,7 +14,7 @@
 #
 # When data is read from `io` it will print something akin to the following on
 # STDERR:
-# ```
+# ```text
 # 00000000  50 52 49 20 2a 20 48 54  54 50 2f 32 2e 30 0d 0a  PRI * HTTP/2.0..
 # 00000010  0d 0a 53 4d 0d 0a 0d 0a                           ..SM....
 # 00000000  00 00 00 04                                       ....

src/io/memory.cr

@@ -18,8 +18,10 @@ class IO::Memory
   #
   # ```
   # io = IO::Memory.new
-  # io.pos  # => 0
-  # io.read # => ""
+  # slice = Bytes.new(1)
+  # io.pos         # => 0
+  # io.read(slice) # => 0
+  # slice          # => Bytes[0]
   # ```
   def initialize(capacity : Int = 64)
     String.check_capacity_in_bounds(capacity)
@@ -41,8 +43,9 @@ class IO::Memory
   # ```
   # slice = Slice.new(6) { |i| ('a'.ord + i).to_u8 }
   # io = IO::Memory.new slice, writeable: false
-  # io.pos  # => 0
-  # io.read # => "abcdef"
+  # io.pos            # => 0
+  # io.read(slice)    # => 6
+  # String.new(slice) # => "abcdef"
   # ```
   def initialize(slice : Bytes, writeable = true)
     @buffer = slice.to_unsafe
@@ -233,9 +236,9 @@ class IO::Memory
   #
   # ```
   # io = IO::Memory.new "hello"
-  # io.gets(2) => "he"
+  # io.gets(2) # => "he"
   # io.rewind
-  # io.gets(2) #=> "he"
+  # io.gets(2) # => "he"
   # ```
   def rewind
     @pos = 0

src/iterator.cr

@@ -42,7 +42,7 @@ require "./enumerable"
 # class Zeros
 #   include Iterator(Int32)
 #
-#   def initialize(@size)
+#   def initialize(@size : Int32)
 #     @produced = 0
 #   end
 #

src/json/from_json.cr

@@ -19,7 +19,7 @@ end
 # the value to deserialize.
 #
 # ```
-# Int32.from_json(%({"main": 1}), root: "main").should eq(1)
+# Int32.from_json(%({"main": 1}), root: "main") # => 1
 # ```
 def Object.from_json(string_or_io, root : String) : self
   parser = JSON::PullParser.new(string_or_io)

src/levenshtein.cr

@@ -3,10 +3,12 @@ module Levenshtein
   # Computes the [levenshtein distance](http://en.wikipedia.org/wiki/Levenshtein_distance) of two strings.
   #
   # ```
-  # levenshtein("algorithm", "altruistic") # => 6
-  # levenshtein("hello", "hallo")          # => 1
-  # levenshtein("こんにちは", "こんちは")           # => 1
-  # levensthein("hey", "hey")              # => 0
+  # require "levenshtein"
+  #
+  # Levenshtein.distance("algorithm", "altruistic") # => 6
+  # Levenshtein.distance("hello", "hallo")          # => 1
+  # Levenshtein.distance("こんにちは", "こんちは")           # => 1
+  # Levenshtein.distance("hey", "hey")              # => 0
   # ```
   def self.distance(string1 : String, string2 : String) : Int32
     return 0 if string1 == string2

src/logger.cr

@@ -23,7 +23,7 @@
 # log.warn("Nothing to do!")
 #
 # begin
-#   File.each_line(path) do |line|
+#   File.each_line("/foo/bar.log") do |line|
 #     unless line =~ /^(\w+) = (.*)$/
 #       log.error("Line in wrong format: #{line}")
 #     end

src/math/math.cr

@@ -66,9 +66,12 @@ module Math
 
   # Calculates the logarithmic gamma of *value*.
   #
-  # lgamma(x) is the same as
   # ```
-  # Math.log(Math.gamma(x).abs)
+  # Math.lgamma(2.96)
+  # ```
+  # is the same as
+  # ```
+  # Math.log(Math.gamma(2.96).abs)
   # ```
   def lgamma(value : Float32)
     {% if flag?(:darwin) %}
@@ -227,7 +230,8 @@ module Math
   # Computes the next highest power of 2 of *v*
   #
   # ```
-  # Math.pw2ceil(33) #=> 64
+  # Math.pw2ceil(33) # => 64
+  # ```
   def pw2ceil(v)
     # Taken from http://graphics.stanford.edu/~seander/bithacks.html#RoundUpPowerOf2
     v -= 1

src/named_tuple.cr

@@ -275,7 +275,7 @@ struct NamedTuple
   #
   # Output:
   #
-  # ```
+  # ```text
   # name = Crystal
   # year = 2011
   # ```
@@ -297,7 +297,7 @@ struct NamedTuple
   #
   # Output:
   #
-  # ```
+  # ```text
   # name
   # year
   # ```
@@ -319,7 +319,7 @@ struct NamedTuple
   #
   # Output:
   #
-  # ```
+  # ```text
   # Crystal
   # 2011
   # ```
@@ -341,7 +341,7 @@ struct NamedTuple
   #
   # Output:
   #
-  # ```
+  # ```text
   # 1) name = Crystal
   # 2) year = 2011
   # ```
@@ -359,7 +359,7 @@ struct NamedTuple
   #
   # ```
   # tuple = {name: "Crystal", year: 2011}
-  # tuple.map { |k, v| "#{name}: #{year}" } # => ["name: Crystal", "year: 2011"]
+  # tuple.map { |k, v| "#{k}: #{v}" } # => ["name: Crystal", "year: 2011"]
   # ```
   def map
     array = Array(typeof(yield first_key_internal, first_value_internal)).new(size)

src/object.cr

@@ -1111,7 +1111,7 @@ class Object
   #
   # ```
   # class StringWrapper
-  #   def initialize(@string)
+  #   def initialize(@string : String)
   #   end
   #
   #   forward_missing_to @string