examples: fix (2022-12)

src/complex.cr

@@ -6,11 +6,11 @@
 # ```
 # require "complex"
 #
-# Complex.new(1, 0)   # => 1.0 + 0.0i
-# Complex.new(5, -12) # => 5.0 - 12.0i
+# Complex.new(1, 0)   # => 1.0 + 0.0.i
+# Complex.new(5, -12) # => 5.0 - 12.0.i
 #
-# 1.to_c # => 1.0 + 0.0i
-# 1.i    # => 0.0 + 1.0i
+# 1.to_c # => 1.0 + 0.0.i
+# 1.i    # => 0.0 + 1.0.i
 # ```
 struct Complex
   # Returns the real part.
@@ -151,9 +151,9 @@ struct Complex
   # ```
   # require "complex"
   #
-  # Complex.new(7, -24).sign        # => (0.28 - 0.96i)
-  # Complex.new(1.0 / 0.0, 24).sign # => (1.0 + 0.0i)
-  # Complex.new(-0.0, +0.0).sign    # => (-0.0 + 0.0i)
+  # Complex.new(7, -24).sign        # => (0.28 - 0.96.i)
+  # Complex.new(1.0 / 0.0, 24).sign # => (1.0 + 0.0.i)
+  # Complex.new(-0.0, +0.0).sign    # => (-0.0 + 0.0.i)
   # ```
   def sign : Complex
     return self if zero?
@@ -199,8 +199,8 @@ struct Complex
   # ```
   # require "complex"
   #
-  # Complex.new(42, 2).conj  # => 42.0 - 2.0i
-  # Complex.new(42, -2).conj # => 42.0 + 2.0i
+  # Complex.new(42, 2).conj  # => 42.0 - 2.0.i
+  # Complex.new(42, -2).conj # => 42.0 + 2.0.i
   # ```
   def conj : Complex
     Complex.new(@real, -@imag)
@@ -353,7 +353,7 @@ module Math
   # ```
   # require "complex"
   #
-  # Math.exp(4 + 2.i) # => -22.720847417619233 + 49.645957334580565i
+  # Math.exp(4 + 2.i) # => -22.720847417619233 + 49.645957334580565.i
   # ```
   def exp(value : Complex) : Complex
     r = exp(value.real)
@@ -365,7 +365,7 @@ module Math
   # ```
   # require "complex"
   #
-  # Math.log(4 + 2.i) # => 1.4978661367769956 + 0.4636476090008061i
+  # Math.log(4 + 2.i) # => 1.4978661367769956 + 0.4636476090008061.i
   # ```
   def log(value : Complex) : Complex
     Complex.new(Math.log(value.abs), value.phase)
@@ -376,7 +376,7 @@ module Math
   # ```
   # require "complex"
   #
-  # Math.log2(4 + 2.i) # => 2.1609640474436813 + 0.6689021062254881i
+  # Math.log2(4 + 2.i) # => 2.1609640474436813 + 0.6689021062254881.i
   # ```
   def log2(value : Complex) : Complex
     log(value) / LOG2
@@ -387,7 +387,7 @@ module Math
   # ```
   # require "complex"
   #
-  # Math.log10(4 + 2.i) # => 0.6505149978319906 + 0.20135959813668655i
+  # Math.log10(4 + 2.i) # => 0.6505149978319906 + 0.20135959813668655.i
   # ```
   def log10(value : Complex) : Complex
     log(value) / LOG10
@@ -399,7 +399,7 @@ module Math
   # ```
   # require "complex"
   #
-  # Math.sqrt(4 + 2.i) # => 2.0581710272714924 + 0.48586827175664565i
+  # Math.sqrt(4 + 2.i) # => 2.0581710272714924 + 0.48586827175664565.i
   # ```
   #
   # Although the imaginary number is defined as i = sqrt(-1),
@@ -409,7 +409,7 @@ module Math
   #
   # ```
   # Math.sqrt(-1.0)         # => -NaN
-  # Math.sqrt(-1.0 + 0.0.i) # => 0.0 + 1.0i
+  # Math.sqrt(-1.0 + 0.0.i) # => 0.0 + 1.0.i
   # ```
   def sqrt(value : Complex) : Complex
     r = value.abs

src/hash.cr

@@ -1102,8 +1102,8 @@ class Hash(K, V)
   #
   # ```
   # h = {"a" => {"b" => [10, 20, 30]}}
-  # h.dig? "a", "b"                # => [10, 20, 30]
-  # h.dig? "a", "b", "c", "d", "e" # => nil
+  # h.dig? "a", "b" # => [10, 20, 30]
+  # h.dig? "a", "x" # => nil
   # ```
   def dig?(key : K, *subkeys)
     if (value = self[key]?) && value.responds_to?(:dig?)
@@ -1121,8 +1121,8 @@ class Hash(K, V)
   #
   # ```
   # h = {"a" => {"b" => [10, 20, 30]}}
-  # h.dig "a", "b"                # => [10, 20, 30]
-  # h.dig "a", "b", "c", "d", "e" # raises KeyError
+  # h.dig "a", "b" # => [10, 20, 30]
+  # h.dig "a", "x" # raises KeyError
   # ```
   def dig(key : K, *subkeys)
     if (value = self[key]) && value.responds_to?(:dig)

src/http/headers.cr

@@ -307,7 +307,7 @@ struct HTTP::Headers
   # The serialization does *not* include a double CRLF sequence at the end.
   #
   # ```
-  # headers = HTTP::Headers{"foo" => "bar", "baz" => %w[qux qox]})
+  # headers = HTTP::Headers{"foo" => "bar", "baz" => %w[qux qox]}
   # headers.serialize # => "foo: bar\r\nbaz: qux\r\nbaz: qox\r\n"
   # ```
   def serialize : String

src/http/status.cr

@@ -74,8 +74,8 @@ enum HTTP::Status
   # ```
   # require "http/status"
   #
-  # HTTP::Status.new(100)  # => CONTINUE
-  # HTTP::Status.new(202)  # => ACCEPTED
+  # HTTP::Status.new(100)  # => HTTP::Status::CONTINUE
+  # HTTP::Status.new(202)  # => HTTP::Status::ACCEPTED
   # HTTP::Status.new(123)  # => 123
   # HTTP::Status.new(1000) # raises ArgumentError
   # ```

src/json/serialization.cr

@@ -98,8 +98,9 @@ module JSON
   #   @a : Int32
   # end
   #
-  # a = A.from_json(%({"a":1,"b":2})) # => A(@json_unmapped={"b" => 2_i64}, @a=1)
-  # a.to_json                         # => {"a":1,"b":2}
+  # a = A.from_json(%({"a":1,"b":2})) # => A(@json_unmapped={"b" => 2}, @a=1)
+  # a.json_unmapped["b"].raw.class    # => Int64
+  # a.to_json                         # => %({"a":1,"b":2})
   # ```
   #
   #

src/json/to_json.cr

@@ -353,8 +353,8 @@ end
 # end
 #
 # timestamp = TimestampHash.from_json(%({"birthdays":{"foo":1459859781,"bar":1567628762}}))
-# timestamp.birthdays # => {"foo" => 2016-04-05 12:36:21 UTC, "bar" => 2019-09-04 20:26:02 UTC)}
-# timestamp.to_json   # => {"birthdays":{"foo":1459859781,"bar":1567628762}}
+# timestamp.birthdays # => {"foo" => 2016-04-05 12:36:21 UTC, "bar" => 2019-09-04 20:26:02 UTC}
+# timestamp.to_json   # => %({"birthdays":{"foo":1459859781,"bar":1567628762}})
 # ```
 #
 # `JSON::HashValueConverter.new` should be used if the nested converter is also
@@ -371,8 +371,8 @@ end
 # end
 #
 # timestamp = TimestampHash.from_json(%({"birthdays":{"foo":"Apr 5, 2016","bar":"Sep 4, 2019"}}))
-# timestamp.birthdays # => {"foo" => 2016-04-05 00:00:00 UTC, "bar" => 2019-09-04 00:00:00 UTC)}
-# timestamp.to_json   # => {"birthdays":{"foo":"Apr 5, 2016","bar":"Sep 4, 2019"}}
+# timestamp.birthdays # => {"foo" => 2016-04-05 00:00:00 UTC, "bar" => 2019-09-04 00:00:00 UTC}
+# timestamp.to_json   # => %({"birthdays":{"foo":"Apr 5, 2016","bar":"Sep 4, 2019"}})
 # ```
 #
 # This implies that `JSON::HashValueConverter(T)` and

src/log.cr

@@ -40,7 +40,7 @@
 #
 # ```
 # module DB
-#   Log = ::Log.for("db") # => Log for db source
+#   Log = ::Log.for("db") # Log for db source
 #
 #   def do_something
 #     Log.info { "this is logged in db source" }
@@ -58,7 +58,7 @@
 #
 # ```
 # class DB::Pool
-#   Log = DB::Log.for("pool") # => Log for db.pool source
+#   Log = DB::Log.for("pool") # Log for db.pool source
 # end
 # ```
 #
@@ -70,7 +70,7 @@
 #
 # ```
 # module DB
-#   Log = ::Log.for(self) # => Log for db source
+#   Log = ::Log.for(self) # Log for db source
 # end
 # ```
 #

src/named_tuple.cr

@@ -31,8 +31,8 @@
 #
 # ```
 # language = {name: "Crystal", year: 2011}
-# language[:name]?         # => 1
-# typeof(language[:name]?) # => Int32
+# language[:name]?         # => "Crystal"
+# typeof(language[:name]?) # => String
 # ```
 #
 # `NamedTuple`'s own instance classes may also be indexed in a similar manner,
@@ -243,9 +243,9 @@ struct NamedTuple
   # Returns `nil` if not found.
   #
   # ```
-  # h = {a: {b: [10, 20, 30]}}
-  # h.dig? "a", "b"                # => [10, 20, 30]
-  # h.dig? "a", "b", "c", "d", "e" # => nil
+  # h = {a: {b: {c: [10, 20]}}, x: {a: "b"}}
+  # h.dig? :a, :b, :c # => [10, 20]
+  # h.dig? "a", "x"   # => nil
   # ```
   def dig?(key : Symbol | String, *subkeys)
     if (value = self[key]?) && value.responds_to?(:dig?)
@@ -262,9 +262,9 @@ struct NamedTuple
   # raises `KeyError`.
   #
   # ```
-  # h = {a: {b: [10, 20, 30]}}
-  # h.dig "a", "b"                # => [10, 20, 30]
-  # h.dig "a", "b", "c", "d", "e" # raises KeyError
+  # h = {a: {b: {c: [10, 20]}}, x: {a: "b"}}
+  # h.dig :a, :b, :c # => [10, 20]
+  # h.dig "a", "x"   # raises KeyError
   # ```
   def dig(key : Symbol | String, *subkeys)
     if (value = self[key]) && value.responds_to?(:dig)

src/semantic_version.cr

@@ -89,8 +89,9 @@ struct SemanticVersion
   # require "semantic_version"
   #
   # current_version = SemanticVersion.new 1, 1, 1, "rc"
-  # current_version.copy_with(patch: 2) # => SemanticVersion(@build=nil, @major=1, @minor=1, @patch=2, @prerelease=SemanticVersion::Prerelease(@identifiers=["rc"]))
-  # current_version.copy_with(prerelease: nil) # => SemanticVersion(@build=nil, @major=1, @minor=1, @patch=2, @prerelease=SemanticVersion::Prerelease(@identifiers=[]))
+  # current_version.copy_with(patch: 2)        # => SemanticVersion(@build=nil, @major=1, @minor=1, @patch=2, @prerelease=SemanticVersion::Prerelease(@identifiers=["rc"]))
+  # current_version.copy_with(prerelease: nil) # => SemanticVersion(@build=nil, @major=1, @minor=1, @patch=1, @prerelease=SemanticVersion::Prerelease(@identifiers=[]))
+  # ```
   def copy_with(major : Int32 = @major, minor : Int32 = @minor, patch : Int32 = @patch, prerelease : String | Prerelease | Nil = @prerelease, build : String? = @build)
     SemanticVersion.new major, minor, patch, prerelease, build
   end
@@ -102,6 +103,7 @@ struct SemanticVersion
   #
   # current_version = SemanticVersion.new 1, 1, 1, "rc"
   # current_version.bump_major # => SemanticVersion(@build=nil, @major=2, @minor=0, @patch=0, @prerelease=SemanticVersion::Prerelease(@identifiers=[]))
+  # ```
   def bump_major
     copy_with(major: major + 1, minor: 0, patch: 0, prerelease: nil, build: nil)
   end
@@ -113,6 +115,7 @@ struct SemanticVersion
   #
   # current_version = SemanticVersion.new 1, 1, 1, "rc"
   # current_version.bump_minor # => SemanticVersion(@build=nil, @major=1, @minor=2, @patch=0, @prerelease=SemanticVersion::Prerelease(@identifiers=[]))
+  # ```
   def bump_minor
     copy_with(minor: minor + 1, patch: 0, prerelease: nil, build: nil)
   end
@@ -125,7 +128,8 @@ struct SemanticVersion
   #
   # current_version = SemanticVersion.new 1, 1, 1, "rc"
   # next_patch = current_version.bump_patch # => SemanticVersion(@build=nil, @major=1, @minor=1, @patch=1, @prerelease=SemanticVersion::Prerelease(@identifiers=[]))
-  # next_patch.bump_patch # => SemanticVersion(@build=nil, @major=1, @minor=1, @patch=2, @prerelease=SemanticVersion::Prerelease(@identifiers=[]))
+  # next_patch.bump_patch                   # => SemanticVersion(@build=nil, @major=1, @minor=1, @patch=2, @prerelease=SemanticVersion::Prerelease(@identifiers=[]))
+  # ```
   def bump_patch
     if prerelease.identifiers.empty?
       copy_with(patch: patch + 1, prerelease: nil, build: nil)

src/string.cr

@@ -3045,7 +3045,7 @@ class String
   # "abcdef" == "abcdefg" # => false
   # "abcdef" == "ABCDEF"  # => false
   #
-  # "abcdef".compare("ABCDEF", case_sensitive: false) == 0 # => true
+  # "abcdef".compare("ABCDEF", case_insensitive: true) == 0 # => true
   # ```
   def ==(other : self) : Bool
     return true if same?(other)

src/string/utf16.cr

@@ -96,10 +96,12 @@ class String
   #
   # ```
   # slice = Slice[104_u16, 105_u16, 0_u16, 55296_u16, 56485_u16, 0_u16]
-  # String.from_utf16(slice) # => "hi\0000𐂥"
+  # String.from_utf16(slice) # => "hi\0000𐂥\u0000"
   # pointer = slice.to_unsafe
-  # string, pointer = String.from_utf16(pointer) # => "hi"
-  # string, pointer = String.from_utf16(pointer) # => "𐂥"
+  # string, pointer = String.from_utf16(pointer)
+  # string # => "hi"
+  # string, pointer = String.from_utf16(pointer)
+  # string # => "𐂥"
   # ```
   #
   # Invalid values are encoded using the unicode replacement char with

src/time.cr

@@ -37,12 +37,12 @@ require "crystal/system/time"
 #
 # ```
 # time = Time.utc(2016, 2, 15, 10, 20, 30)
-# time.to_s # => 2016-02-15 10:20:30 UTC
+# time.to_s # => "2016-02-15 10:20:30 UTC"
 # time = Time.local(2016, 2, 15, 10, 20, 30, location: Time::Location.load("Europe/Berlin"))
-# time.to_s # => 2016-02-15 10:20:30 +01:00 Europe/Berlin
+# time.to_s # => "2016-02-15 10:20:30 +01:00"
 # # The time-of-day can be omitted and defaults to midnight (start of day):
 # time = Time.utc(2016, 2, 15)
-# time.to_s # => 2016-02-15 00:00:00 UTC
+# time.to_s # => "2016-02-15 00:00:00 UTC"
 # ```
 #
 # ### Retrieving Time Information
@@ -660,7 +660,7 @@ struct Time
   # change:
   #
   # ```
-  # start = Time.new(2017, 10, 28, 13, 37, location: Time::Location.load("Europe/Berlin"))
+  # start = Time.local(2017, 10, 28, 13, 37, location: Time::Location.load("Europe/Berlin"))
   # one_day_later = start.shift days: 1
   #
   # one_day_later - start # => 25.hours

src/time/span.cr

@@ -105,7 +105,7 @@ struct Time::Span
   #
   # ```
   # Time::Span.new(days: 1)                                                   # => 1.00:00:00
-  # Time::Span.new(days: 1, hours: 2, minutes: 3)                             # => 01:02:03
+  # Time::Span.new(days: 1, hours: 2, minutes: 3)                             # => 1.02:03:00
   # Time::Span.new(days: 1, hours: 2, minutes: 3, seconds: 4, nanoseconds: 5) # => 1.02:03:04.000000005
   # ```
   def self.new(*, days : Int = 0, hours : Int = 0, minutes : Int = 0, seconds : Int = 0, nanoseconds : Int = 0)

src/uuid/yaml.cr

@@ -17,7 +17,7 @@ struct UUID
   #   property id : UUID
   # end
   #
-  # example = Example.from_yaml("uuid: 50a11da6-377b-4bdf-b9f0-076f9db61c93")
+  # example = Example.from_yaml("id: 50a11da6-377b-4bdf-b9f0-076f9db61c93")
   # example.id # => UUID(50a11da6-377b-4bdf-b9f0-076f9db61c93)
   # ```
   def self.new(ctx : YAML::ParseContext, node : YAML::Nodes::Node)

src/yaml/serialization.cr

@@ -97,7 +97,8 @@ module YAML
   #   @a : Int32
   # end
   #
-  # a = A.from_yaml("---\na: 1\nb: 2\n") # => A(@yaml_unmapped={"b" => 2_i64}, @a=1)
+  # a = A.from_yaml("---\na: 1\nb: 2\n") # => A(@yaml_unmapped={"b" => 2}, @a=1)
+  # a.yaml_unmapped["b"].raw.class       # => Int64
   # a.to_yaml                            # => "---\na: 1\nb: 2\n"
   # ```
   #