fix example codes (2018-04) (crystal-lang#5912)

src/complex.cr

@@ -63,8 +63,8 @@ struct Complex
   # number form, using the Pythagorean theorem.
   #
   # ```
-  # Complex.new(42, 2).abs  # => 42.047592083257278
-  # Complex.new(-42, 2).abs # => 42.047592083257278
+  # Complex.new(42, 2).abs  # => 42.04759208325728
+  # Complex.new(-42, 2).abs # => 42.04759208325728
   # ```
   def abs
     Math.hypot(@real, @imag)

src/exception.cr

@@ -121,7 +121,7 @@ end
 # Raised when attempting to divide an integer by 0.
 #
 # ```
-# 1 / 0 # raises DivisionByZero (Division by 0)
+# 1 / 0 # raises DivisionByZeroError (Division by 0)
 # ```
 class DivisionByZeroError < Exception
   def initialize(message = "Division by 0")

src/http/common.cr

@@ -275,6 +275,7 @@ module HTTP
   # string = %q("foo\ bar")
   # io = IO::Memory.new
   # HTTP.quote_string(string, io)
+  # io.rewind
   # io.gets_to_end # => %q(\"foo\\\ bar\")
   # ```
   def self.quote_string(string, io)

src/http/formdata.cr

@@ -39,7 +39,7 @@ require "./formdata/**"
 #
 # To test the server, use the curl command below.
 #
-# ```
+# ```console
 # $ curl http://localhost:8085/ -F name=foo -F file=@/path/to/test.file
 # /tmp/upload.Yxn7cc
 # ```
@@ -197,7 +197,7 @@ module HTTP::FormData
   # response.close
   #
   # response.headers["Content-Type"] # => "multipart/form-data; boundary=\"boundary\""
-  # io.to_s                          # => "HTTP/1.1 200 OK\r\nContent-Type: multipart/form-data; boundary=\"boundary\"\r\n ...
+  # io.to_s                          # => "HTTP/1.1 200 OK\r\nContent-Type: multipart/form-data; boundary=\"boundary\"\r\nContent-Length: 75\r\n\r\n--boundary\r\nContent-Disposition: form-data; name=\"foo\"\r\n\r\nbar\r\n--boundary--"
   # ```
   #
   # See: `FormData::Builder`

src/http/formdata/builder.cr

@@ -8,7 +8,7 @@ module HTTP::FormData
   # builder = HTTP::FormData::Builder.new(io, "aA47")
   # builder.field("name", "joe")
   # file = IO::Memory.new("file contents")
-  # builder.file("upload", file, FileMetadata.new(filename: "test.txt"))
+  # builder.file("upload", file, HTTP::FormData::FileMetadata.new(filename: "test.txt"))
   # builder.finish
   # io.to_s # => "--aA47\r\nContent-Disposition: form-data; name=\"name\"\r\n\r\njoe\r\n--aA47\r\nContent-Disposition: form-data; name=\"upload\"; filename=\"test.txt\"\r\n\r\nfile contents\r\n--aA47--"
   # ```

src/http/formdata/parser.cr

@@ -19,7 +19,7 @@ module HTTP::FormData
     # parser = HTTP::FormData::Parser.new(IO::Memory.new(form_data), "aA40")
     # parser.next do |part|
     #   part.name                    # => "field1"
-    #   part.io.gets_to_end          # => "field data"
+    #   part.body.gets_to_end        # => "field data"
     #   part.filename                # => "foo.txt"
     #   part.size                    # => 13
     #   part.headers["Content-Type"] # => "text/plain"

src/http/multipart/builder.cr

@@ -4,7 +4,7 @@ module HTTP::Multipart
   # ### Example
   #
   # ```
-  # io = IO::Memory.new
+  # io = IO::Memory.new # This is a stub. Actually, any IO can be used.
   # multipart = HTTP::Multipart::Builder.new(io)
   # multipart.body_part HTTP::Headers{"Content-Type" => "text/plain"}, "hello!"
   # multipart.finish
@@ -25,6 +25,7 @@ module HTTP::Multipart
     # boundary parameter added.
     #
     # ```
+    # io = IO::Memory.new # This is a stub. Actually, any IO can be used.
     # builder = HTTP::Multipart::Builder.new(io, "a4VF")
     # builder.content_type("mixed") # => "multipart/mixed; boundary=\"a4VF\""
     # ```

src/http/params.cr

@@ -79,7 +79,7 @@ module HTTP
     # Returns the given key value pairs as a url-encoded HTTP form/query.
     #
     # ```
-    # HTTP::Params.encode({"foo" => "bar", "baz" => "qux"}) # => foo=bar&baz=qux
+    # HTTP::Params.encode({"foo" => "bar", "baz" => "qux"}) # => "foo=bar&baz=qux"
     # ```
     def self.encode(hash : Hash(String, String))
       build do |builder|
@@ -92,7 +92,7 @@ module HTTP
     # Returns the given key value pairs as a url-encoded HTTP form/query.
     #
     # ```
-    # HTTP::Params.encode({foo: "bar", baz: "qux"}) # => foo=bar&baz=qux
+    # HTTP::Params.encode({foo: "bar", baz: "qux"}) # => "foo=bar&baz=qux"
     # ```
     def self.encode(named_tuple : NamedTuple)
       build do |builder|

src/openssl/digest/digest_io.cr

@@ -12,7 +12,7 @@ module OpenSSL
   # io = OpenSSL::DigestIO.new(underlying_io, "SHA256")
   # buffer = Bytes.new(256)
   # io.read(buffer)
-  # io.digest # => 2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae
+  # io.digest.hexstring # => "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"
   # ```
   class DigestIO < IO
     getter io : IO

src/regex.cr

@@ -218,7 +218,7 @@ class Regex
   #
   # ```
   # /ab+c/ix.options      # => Regex::Options::IGNORE_CASE | Regex::Options::EXTENDED
-  # /ab+c/ix.options.to_s # => "IGNORE_CASE, EXTENDED"
+  # /ab+c/ix.options.to_s # => "IGNORE_CASE | EXTENDED"
   # ```
   getter options : Options
 

src/spec.cr

@@ -50,7 +50,7 @@ require "./spec/dsl"
 # By convention, specs live in the `spec` directory of a project. You can compile
 # and run the specs of a project by running `crystal spec`.
 #
-# ```shell
+# ```console
 # # Run  all specs in files matching spec/**/*_spec.cr
 # crystal spec
 #

src/static_array.cr

@@ -169,7 +169,7 @@ struct StaticArray(T, N)
   #
   # ```
   # array = StaticArray[1, 2.5, "a"]
-  # tuple.map &.to_s # => StaticArray["1", "2.5", "a"]
+  # array.map &.to_s # => StaticArray["1", "2.5", "a"]
   # ```
   def map(&block : T -> U) forall U
     StaticArray(U, N).new { |i| yield to_unsafe[i] }

src/string.cr

@@ -3853,7 +3853,7 @@ class String
   # Returns a representation of `self` using character escapes for special characters and wrapped in quotes.
   #
   # ```
-  # "\u{1f48e} - à la carte\n".inspect # => %("\u{1E48E} - à la carte\\n")
+  # "\u{1f48e} - à la carte\n".inspect # => %("\u{1F48E} - à la carte\\n")
   # ```
   def inspect : String
     super
@@ -3869,7 +3869,7 @@ class String
   # Returns a representation of `self` using character escapes for special characters but not wrapped in quotes.
   #
   # ```
-  # "\u{1f48e} - à la carte\n".inspect_unquoted # => %(\u{1E48E} - à la carte\\n)
+  # "\u{1f48e} - à la carte\n".inspect_unquoted # => %(\u{1F48E} - à la carte\\n)
   # ```
   def inspect_unquoted : String
     String.build do |io|
@@ -3888,7 +3888,7 @@ class String
   # and and non-ascii characters (unicode codepoints > 128), wrapped in quotes.
   #
   # ```
-  # "\u{1f48e} - à la carte\n".dump # => %("\\u1f48e - \\u00e0 la carte\\n")
+  # "\u{1f48e} - à la carte\n".dump # => %("\\u{1F48E} - \\u00E0 la carte\\n")
   # ```
   def dump : String
     String.build do |io|
@@ -3908,7 +3908,7 @@ class String
   # and and non-ascii characters (unicode codepoints > 128), but not wrapped in quotes.
   #
   # ```
-  # "\u{1f48e} - à la carte\n".dump_unquoted # => %(\\u1f48e - \\u00e0 la carte\\n)
+  # "\u{1f48e} - à la carte\n".dump_unquoted # => %(\\u{1F48E} - \\u00E0 la carte\\n)
   # ```
   def dump_unquoted : String
     String.build do |io|

src/string_scanner.cr

@@ -85,7 +85,7 @@ class StringScanner
   # s.scan(/\w+/)   # => "test"
   # s.scan(/\w+/)   # => nil
   # s.scan(/\s\w+/) # => " string"
-  # s.scan(/.*/)    # => nil
+  # s.scan(/.*/)    # => ""
   # ```
   def scan(pattern)
     match(pattern, advance: true, options: Regex::Options::ANCHORED)

src/time.cr

@@ -114,7 +114,7 @@ struct Time
   #
   # ```
   # time = Time.new(2016, 2, 15)
-  # time.day_of_week # => Monday
+  # time.day_of_week # => Time::DayOfWeek::Monday
   # ```
   #
   # Alternatively, you can use question methods:

src/time/location.cr

@@ -13,15 +13,15 @@ require "./location/loader"
 # Initializing a `Time` instance with specified `Location`:
 #
 # ```
-# time = Time.new(2016, 2, 15, 21, 1, 10, location)
+# time = Time.new(2016, 2, 15, 21, 1, 10, location: location)
 # ```
 #
 # Alternatively, you can switch the `Location` for any `Time` instance:
 #
 # ```
-# time.location # => Europe/Berlin
-# time.in(Time::Location.load("Asia/Jerusalem"))
-# time.location # => Asia/Jerusalem
+# time.location.to_s # => "Europe/Berlin"
+# time = time.in(Time::Location.load("Asia/Jerusalem"))
+# time.location.to_s # => "Asia/Jerusalem"
 # ```
 #
 # There are also a few special conversions: