Merge pull request #5936 from straight-shoota/jm/docs/json-yaml-read-…

…file

Docs: Add examples for parse(IO) to JSON, YAML

src/json.cr

@@ -1,14 +1,14 @@
 # The JSON module allows parsing and generating [JSON](http://json.org/) documents.
 #
-# ### Parsing and generating with `JSON#mapping`
+# ### Parsing and generating with `JSON.mapping`
 #
-# Use `JSON#mapping` to define how an object is mapped to JSON, making it
+# Use `JSON.mapping` to define how an object is mapped to JSON, making it
 # the recommended easy, type-safe and efficient option for parsing and generating
 # JSON. Refer to that module's documentation to learn about it.
 #
-# ### Parsing with `JSON#parse`
+# ### Parsing with `JSON.parse`
 #
-# `JSON#parse` will return an `Any`, which is a convenient wrapper around all possible JSON types,
+# `JSON.parse` will return an `Any`, which is a convenient wrapper around all possible JSON types,
 # making it easy to traverse a complex JSON structure but requires some casts from time to time,
 # mostly via some method invocations.
 #
@@ -26,7 +26,18 @@
 # value[0].as_i + 10 # => 11
 # ```
 #
-# The above is useful for dealing with a dynamic JSON structure but is slower than using `JSON#mapping`.
+# `JSON.parse` can read from an `IO` directly (such as a file) which saves
+# allocating a string:
+#
+# ```
+# require "json"
+#
+# json = File.open("path/to/file.json") do |file|
+#   JSON.parse(file)
+# end
+# ```
+#
+# Parsing with `JSON.parse` is useful for dealing with a dynamic JSON structure but is slower than using `JSON.mapping`.
 #
 # ### Generating with `JSON.build`
 #
@@ -55,7 +66,7 @@
 #
 # `to_json`, `to_json(IO)` and `to_json(JSON::Builder)` methods are provided
 # for primitive types, but you need to define `to_json(JSON::Builder)`
-# for custom objects, either manually or using `JSON#mapping`.
+# for custom objects, either manually or using `JSON.mapping`.
 module JSON
   # Generic JSON error.
   class Error < Exception

src/yaml.cr

@@ -7,7 +7,7 @@ require "base64"
 #
 # ### Parsing with `#parse` and `#parse_all`
 #
-# `YAML#parse` will return an `Any`, which is a convenient wrapper around all possible
+# `YAML.parse` will return an `Any`, which is a convenient wrapper around all possible
 # YAML core types, making it easy to traverse a complex YAML structure but requires
 # some casts from time to time, mostly via some method invocations.
 #
@@ -25,6 +25,17 @@ require "base64"
 # data["foo"]["bar"]["baz"][1].as_s # => "fox"
 # ```
 #
+# `YAML.parse` can read from an `IO` directly (such as a file) which saves
+# allocating a string:
+#
+# ```
+# require "yaml"
+#
+# yaml = File.open("path/to/file.yml") do |file|
+#   YAML.parse(file)
+# end
+# ```
+#
 # ### Parsing with `from_yaml`
 #
 # A type `T` can be deserialized from YAML by invoking `T.from_yaml(string_or_io)`.