examples: fix (2020-10) (#9818)

* examples: fix (2020-10)

* examples: fix to keep the nuance for the two cases: found and default.

* examples: leave it as is about string stuffs.

* examples: Modified the Log::StaticFormatter#source example to be a full setup

* Update src/openssl/digest/digest_io.cr

Co-authored-by: Brian J. Cardiff <[email protected]>

src/file.cr

@@ -723,6 +723,7 @@ class File < IO::FileDescriptor
   # Permission bits are copied too.
   #
   # ```
+  # File.touch("afile")
   # File.chmod("afile", 0o600)
   # File.copy("afile", "afile_copy")
   # File.info("afile_copy").permissions.value # => 0o600

src/file_utils.cr

@@ -83,6 +83,7 @@ module FileUtils
   # ```
   # require "file_utils"
   #
+  # File.touch("afile")
   # File.chmod("afile", 0o600)
   # FileUtils.cp("afile", "afile_copy")
   # File.info("afile_copy").permissions.value # => 0o600

src/http/params.cr

@@ -221,6 +221,7 @@ module HTTP
     # *default* value when there is no such param.
     #
     # ```
+    # params["email"] = "[email protected]"
     # params.fetch("email", "[email protected]")           # => "[email protected]"
     # params.fetch("non_existent_param", "default value") # => "default value"
     # ```
@@ -232,6 +233,7 @@ module HTTP
     # of provided block when there is no such param.
     #
     # ```
+    # params.delete("email")
     # params.fetch("email") { raise "Email is missing" }              # raises "Email is missing"
     # params.fetch("non_existent_param") { "default computed value" } # => "default computed value"
     # ```

src/http/status.cr

@@ -150,7 +150,7 @@ enum HTTP::Status
   # require "http/status"
   #
   # HTTP::Status::INTERNAL_SERVER_ERROR.server_error? # => true
-  # HTTP::Status::METHOD_NOT_ALLOWED.server_error?    # => true
+  # HTTP::Status::METHOD_NOT_ALLOWED.server_error?    # => false
   # ```
   def server_error? : Bool
     500 <= code <= 599

src/http/web_socket.cr

@@ -121,7 +121,7 @@ class HTTP::WebSocket
   #
   # ```
   # # Open websocket connection
-  # ws = WebSocket.new(uri)
+  # ws = HTTP::WebSocket.new("websocket.example.com", "/chat")
   #
   # # Set callback
   # ws.on_message do |msg|

src/json/to_json.cr

@@ -216,7 +216,7 @@ end
 #   include JSON::Serializable
 #
 #   @[JSON::Field(converter: JSON::HashValueConverter(Time::EpochConverter))]
-#   birthdays : Hash(String, Time)
+#   property birthdays : Hash(String, Time)
 # end
 #
 # timestamp = TimestampHash.from_json(%({"birthdays":{"foo":1459859781,"bar":1567628762}}))
@@ -246,7 +246,7 @@ end
 #   include JSON::Serializable
 #
 #   @[JSON::Field(converter: Time::EpochConverter)]
-#   birth_date : Time
+#   property birth_date : Time
 # end
 #
 # person = Person.from_json(%({"birth_date": 1459859781}))
@@ -270,7 +270,7 @@ end
 #   include JSON::Serializable
 #
 #   @[JSON::Field(converter: Time::EpochMillisConverter)]
-#   value : Time
+#   property value : Time
 # end
 #
 # timestamp = Timestamp.from_json(%({"value": 1459860483856}))
@@ -297,7 +297,7 @@ end
 #   include JSON::Serializable
 #
 #   @[JSON::Field(converter: String::RawConverter)]
-#   value : String
+#   property value : String
 # end
 #
 # raw = Raw.from_json(%({"value": 123456789876543212345678987654321}))

src/log/format.cr

@@ -36,7 +36,9 @@ class Log
   #
   # This can be used to create efficient formatters:
   # ```
-  # struct MyFormat < Log::StaticFormat
+  # require "log"
+  #
+  # struct MyFormat < Log::StaticFormatter
   #   def run
   #     string "- "
   #     severity
@@ -90,7 +92,9 @@ class Log
     # Parameters `before` and `after` can be provided to be written around
     # the value.
     # ```
-    # source(before: '[', after: ']') # => [http.server]
+    # Log.define_formatter TestFormatter, "#{source(before: '[', after: "] ")}#{message}"
+    # Log.setup(:info, Log::IOBackend.new(formatter: TestFormatter))
+    # Log.for("foo.bar").info { "Hello" } # => - [foo.bar] Hello
     # ```
     def source(*, before = nil, after = nil)
       if @entry.source.size > 0

src/string.cr

@@ -1235,7 +1235,7 @@ class String
   # ```
   # io = IO::Memory.new
   # "hEllO".downcase io
-  # io.to_s # => hello
+  # io.to_s # => "hello"
   # ```
   def downcase(io : IO, options : Unicode::CaseOptions = :none) : Nil
     each_char do |char|
@@ -1270,7 +1270,7 @@ class String
   # ```
   # io = IO::Memory.new
   # "hEllO".upcase io
-  # io.to_s # => HELLO
+  # io.to_s # => "HELLO"
   # ```
   def upcase(io : IO, options : Unicode::CaseOptions = :none) : Nil
     each_char do |char|
@@ -1312,7 +1312,7 @@ class String
   # ```
   # io = IO::Memory.new
   # "hEllO".capitalize io
-  # io.to_s # => Hello
+  # io.to_s # => "Hello"
   # ```
   def capitalize(io : IO, options : Unicode::CaseOptions = :none) : Nil
     each_char_with_index do |char, i|
@@ -1357,7 +1357,7 @@ class String
   # ```
   # io = IO::Memory.new
   # "x-men: the last stand".titleize io
-  # io.to_s # => X-men: The Last Stand
+  # io.to_s # => "X-men: The Last Stand"
   # ```
   def titleize(io : IO, options : Unicode::CaseOptions = :none) : Nil
     upcase_next = true

src/yaml/to_yaml.cr

@@ -161,7 +161,7 @@ end
 #   include YAML::Serializable
 #
 #   @[YAML::Field(converter: YAML::ArrayConverter(Time::EpochConverter))]
-#   values : Array(Time)
+#   property values : Array(Time)
 # end
 #
 # timestamp = Timestamp.from_yaml(%({"values":[1459859781,1567628762]}))