rbs 2.8.4 → 3.8.1

data/stdlib/json/0/json.rbs

@@ -8,6 +8,8 @@ end
 
 interface _JsonWrite
   def write: (String json) -> void
+
+  def flush: () -> void
 end
 
 interface _JsonReadableIO
@@ -115,7 +117,6 @@ type json_state = singleton(JSON::Ext::Generator::State) | singleton(JSON::Pure:
 #     name is double-quoted text; the values may be any JSON values:
 #         {"a": "foo", "b": 1, "c": 1.0, "d": 2.0e2, "e": true, "f": false, "g": null}
 #
-#
 # A JSON array or object may contain nested arrays, objects, and scalars to any
 # depth:
 #     {"foo": {"bar": 1, "baz": 2}, "bat": [0, 1, 2]}
@@ -134,13 +135,11 @@ type json_state = singleton(JSON::Ext::Generator::State) | singleton(JSON::Pure:
 # *   `JSON.parse(source, opts)`
 # *   `JSON.parse!(source, opts)`
 #
-#
 # where
 # *   `source` is a Ruby object.
 # *   `opts` is a Hash object containing options that control both input allowed
 #     and output formatting.
 #
-#
 # The difference between the two methods is that JSON.parse! omits some checks
 # and may not be safe for some `source` data; use it only for data from trusted
 # sources. Use the safer method JSON.parse for less trusted sources.
@@ -298,7 +297,6 @@ type json_state = singleton(JSON::Ext::Generator::State) | singleton(JSON::Pure:
 # *   `opts` is a Hash object containing options that control both input allowed
 #     and output formatting.
 #
-#
 # #### Generating JSON from Arrays
 #
 # When the source is a Ruby Array, JSON.generate returns a String containing a
@@ -385,6 +383,15 @@ type json_state = singleton(JSON::Ext::Generator::State) | singleton(JSON::Pure:
 #     # Raises JSON::NestingError (nesting of 2 is too deep):
 #     JSON.generate(obj, max_nesting: 2)
 #
+# ###### Escaping Options
+#
+# Options `script_safe` (boolean) specifies wether `'\u2028'`, `'\u2029'` and
+# `'/'` should be escaped as to make the JSON object safe to interpolate in
+# script tags.
+#
+# Options `ascii_only` (boolean) specifies wether all characters outside the
+# ASCII range should be escaped.
+#
 # ###### Output Options
 #
 # The default formatting options generate the most compact JSON data, all on one
@@ -408,7 +415,6 @@ type json_state = singleton(JSON::Ext::Generator::State) | singleton(JSON::Pure:
 #     inserted before the colon in each JSON object's pair; defaults to the
 #     empty String, `''`.
 #
-#
 # In this example, `obj` is used first to generate the shortest JSON data (no
 # whitespace), then again with all formatting options specified:
 #
@@ -456,7 +462,6 @@ type json_state = singleton(JSON::Ext::Generator::State) | singleton(JSON::Pure:
 # *   JSON.parse, called with option `create_additions`, uses that information
 #     to create a proper Ruby object.
 #
-#
 # This example shows a Range being generated into JSON and parsed back into
 # Ruby, both without and with the addition for Range:
 #     ruby = Range.new(0, 2)
@@ -468,13 +473,13 @@ type json_state = singleton(JSON::Ext::Generator::State) | singleton(JSON::Pure:
 #     json1 = JSON.generate(ruby)
 #     ruby1 = JSON.parse(json1, create_additions: true)
 #     # Make a nice display.
-#     display = <<EOT
-#     Generated JSON:
-#       Without addition:  #{json0} (#{json0.class})
-#       With addition:     #{json1} (#{json1.class})
-#     Parsed JSON:
-#       Without addition:  #{ruby0.inspect} (#{ruby0.class})
-#       With addition:     #{ruby1.inspect} (#{ruby1.class})
+#     display = <<~EOT
+#       Generated JSON:
+#         Without addition:  #{json0} (#{json0.class})
+#         With addition:     #{json1} (#{json1.class})
+#       Parsed JSON:
+#         Without addition:  #{ruby0.inspect} (#{ruby0.class})
+#         With addition:     #{ruby1.inspect} (#{ruby1.class})
 #     EOT
 #     puts display
 #
@@ -508,7 +513,6 @@ type json_state = singleton(JSON::Ext::Generator::State) | singleton(JSON::Pure:
 # *   Symbol: `require 'json/add/symbol'`
 # *   Time: `require 'json/add/time'`
 #
-#
 # To reduce punctuation clutter, the examples below show the generated JSON via
 # `puts`, rather than the usual `inspect`,
 #
@@ -651,13 +655,13 @@ type json_state = singleton(JSON::Ext::Generator::State) | singleton(JSON::Pure:
 #     json1 = JSON.generate(foo1)
 #     obj1 = JSON.parse(json1, create_additions: true)
 #     #   Make a nice display.
-#     display = <<EOT
-#     Generated JSON:
-#       Without custom addition:  #{json0} (#{json0.class})
-#       With custom addition:     #{json1} (#{json1.class})
-#     Parsed JSON:
-#       Without custom addition:  #{obj0.inspect} (#{obj0.class})
-#       With custom addition:     #{obj1.inspect} (#{obj1.class})
+#     display = <<~EOT
+#       Generated JSON:
+#         Without custom addition:  #{json0} (#{json0.class})
+#         With custom addition:     #{json1} (#{json1.class})
+#       Parsed JSON:
+#         Without custom addition:  #{obj0.inspect} (#{obj0.class})
+#         With custom addition:     #{obj1.inspect} (#{obj1.class})
 #     EOT
 #     puts display
 #
@@ -705,7 +709,7 @@ module JSON
   #
   def self.create_id=: (_ToS create_id) -> _ToS
 
-  def self.deep_const_get: (_ToS path) -> untyped
+  def self.deep_const_get: (interned path) -> untyped
 
   # <!--
   #   rdoc-file=ext/json/lib/json/common.rb
@@ -722,7 +726,6 @@ module JSON
   # *   Argument `limit`, if given, is passed to JSON.generate as option
   #     `max_nesting`.
   #
-  #
   # ---
   #
   # When argument `io` is not given, returns the JSON String generated from `obj`:
@@ -747,14 +750,14 @@ module JSON
   # <!-- rdoc-file=ext/json/lib/json/common.rb -->
   # Sets or returns the default options for the JSON.dump method. Initially:
   #     opts = JSON.dump_default_options
-  #     opts # => {:max_nesting=>false, :allow_nan=>true, :escape_slash=>false}
+  #     opts # => {:max_nesting=>false, :allow_nan=>true}
   #
   def self.dump_default_options: () -> json_options
 
   # <!-- rdoc-file=ext/json/lib/json/common.rb -->
   # Sets or returns the default options for the JSON.dump method. Initially:
   #     opts = JSON.dump_default_options
-  #     opts # => {:max_nesting=>false, :allow_nan=>true, :escape_slash=>false}
+  #     opts # => {:max_nesting=>false, :allow_nan=>true}
   #
   def self.dump_default_options=: (json_options) -> json_options
 
@@ -819,9 +822,7 @@ module JSON
   def self?.generate: (_ToJson obj, ?json_options opts) -> String
 
   # <!-- rdoc-file=ext/json/lib/json/common.rb -->
-  # Returns the JSON generator module that is used by JSON. This is either
-  # JSON::Ext::Generator or JSON::Pure::Generator:
-  #     JSON.generator # => JSON::Ext::Generator
+  # Returns the JSON generator module that is used by JSON.
   #
   def self.generator: () -> json_generator
 
@@ -841,6 +842,15 @@ module JSON
   # -->
   # Returns the Ruby objects created by parsing the given `source`.
   #
+  # BEWARE: This method is meant to serialise data from trusted user input, like
+  # from your own database server or clients under your control, it could be
+  # dangerous to allow untrusted users to pass JSON sources into it. If you must
+  # use it, use JSON.unsafe_load instead to make it clear.
+  #
+  # Since JSON version 2.8.0, `load` emits a deprecation warning when a non native
+  # type is deserialized, without `create_additions` being explicitly enabled, and
+  # in JSON version 3.0, `load` will have `create_additions` disabled by default.
+  #
   # *   Argument `source` must be, or be convertible to, a String:
   #     *   If `source` responds to instance method `to_str`, `source.to_str`
   #         becomes the source.
@@ -851,37 +861,31 @@ module JSON
   #     *   If both of the following are true, source becomes the String `'null'`:
   #         *   Option `allow_blank` specifies a truthy value.
   #         *   The source, as defined above, is `nil` or the empty String `''`.
-  #
   #     *   Otherwise, `source` remains the source.
-  #
   # *   Argument `proc`, if given, must be a Proc that accepts one argument. It
   #     will be called recursively with each result (depth-first order). See
-  #     details below. BEWARE: This method is meant to serialise data from trusted
-  #     user input, like from your own database server or clients under your
-  #     control, it could be dangerous to allow untrusted users to pass JSON
-  #     sources into it.
+  #     details below.
   # *   Argument `opts`, if given, contains a Hash of options for the parsing. See
   #     [Parsing Options](#module-JSON-label-Parsing+Options). The default options
   #     can be changed via method JSON.load_default_options=.
   #
-  #
   # ---
   #
   # When no `proc` is given, modifies `source` as above and returns the result of
   # `parse(source, opts)`;  see #parse.
   #
   # Source for following examples:
-  #     source = <<-EOT
-  #     {
-  #     "name": "Dave",
-  #       "age" :40,
-  #       "hats": [
-  #         "Cattleman's",
-  #         "Panama",
-  #         "Tophat"
-  #       ]
-  #     }
-  #     EOT
+  #     source = <<~JSON
+  #       {
+  #         "name": "Dave",
+  #         "age" :40,
+  #         "hats": [
+  #           "Cattleman's",
+  #           "Panama",
+  #           "Tophat"
+  #         ]
+  #       }
+  #     JSON
   #
   # Load a String:
   #     ruby = JSON.load(source)
@@ -907,7 +911,6 @@ module JSON
   # *   Recursively calls `proc(result)`.
   # *   Returns the final result.
   #
-  #
   # Example:
   #     require 'json'
   #
@@ -971,6 +974,28 @@ module JSON
   #
   def self?.load: (string | _JsonReadableIO | _JsonRead source, ?Proc proc, ?json_options options) -> untyped
 
+  # <!--
+  #   rdoc-file=ext/json/lib/json/common.rb
+  #   - JSON.load_file(path, opts={}) -> object
+  # -->
+  # Calls:
+  #     parse(File.read(path), opts)
+  #
+  # See method #parse.
+  #
+  def self?.load_file: (string path, ?json_options opts) -> untyped
+
+  # <!--
+  #   rdoc-file=ext/json/lib/json/common.rb
+  #   - JSON.load_file!(path, opts = {})
+  # -->
+  # Calls:
+  #     JSON.parse!(File.read(path, opts))
+  #
+  # See method #parse!
+  #
+  def self?.load_file!: (string path, ?json_options opts) -> untyped
+
   # <!-- rdoc-file=ext/json/lib/json/common.rb -->
   # Sets or returns default options for the JSON.load method. Initially:
   #     opts = JSON.load_default_options
@@ -1014,17 +1039,17 @@ module JSON
   # \JSON](#module-JSON-label-Parsing+JSON).
   #
   # Parses nested JSON objects:
-  #     source = <<-EOT
-  #     {
-  #     "name": "Dave",
-  #       "age" :40,
-  #       "hats": [
-  #         "Cattleman's",
-  #         "Panama",
-  #         "Tophat"
-  #       ]
-  #     }
-  #     EOT
+  #     source = <<~JSON
+  #       {
+  #       "name": "Dave",
+  #         "age" :40,
+  #         "hats": [
+  #           "Cattleman's",
+  #           "Panama",
+  #           "Tophat"
+  #         ]
+  #       }
+  #     JSON
   #     ruby = JSON.parse(source)
   #     ruby # => {"name"=>"Dave", "age"=>40, "hats"=>["Cattleman's", "Panama", "Tophat"]}
   #
@@ -1053,9 +1078,7 @@ module JSON
   def self?.parse!: (string source, ?json_options opts) -> untyped
 
   # <!-- rdoc-file=ext/json/lib/json/common.rb -->
-  # Returns the JSON parser class that is used by JSON. This is either
-  # JSON::Ext::Parser or JSON::Pure::Parser:
-  #     JSON.parser # => JSON::Ext::Parser
+  # Returns the JSON parser class that is used by JSON.
   #
   def self.parser: () -> json_parser
 
@@ -1106,29 +1129,25 @@ module JSON
 
   # <!--
   #   rdoc-file=ext/json/lib/json/common.rb
-  #   - restore(source, proc = nil, options = {})
+  #   - restore(source, proc = nil, options = nil)
   # -->
   #
   alias self.restore self.load
 
   # <!--
   #   rdoc-file=ext/json/lib/json/common.rb
-  #   - restore(source, proc = nil, options = {})
+  #   - restore(source, proc = nil, options = nil)
   # -->
   #
   alias restore load
 
   # <!-- rdoc-file=ext/json/lib/json/common.rb -->
-  # Sets or Returns the JSON generator state class that is used by JSON. This is
-  # either JSON::Ext::Generator::State or JSON::Pure::Generator::State:
-  #     JSON.state # => JSON::Ext::Generator::State
+  # Sets or Returns the JSON generator state class that is used by JSON.
   #
   def self.state: () -> json_state
 
   # <!-- rdoc-file=ext/json/lib/json/common.rb -->
-  # Sets or Returns the JSON generator state class that is used by JSON. This is
-  # either JSON::Ext::Generator::State or JSON::Pure::Generator::State:
-  #     JSON.state # => JSON::Ext::Generator::State
+  # Sets or Returns the JSON generator state class that is used by JSON.
   #
   def self.state=: (json_state) -> json_state
 
@@ -1151,9 +1170,6 @@ JSON::PRETTY_STATE_PROTOTYPE: json_state
 
 JSON::SAFE_STATE_PROTOTYPE: json_state
 
-# <!-- rdoc-file=ext/json/lib/json/version.rb -->
-# JSON version
-#
 JSON::VERSION: String
 
 JSON::VERSION_ARRAY: Array[Integer]
@@ -1164,6 +1180,43 @@ JSON::VERSION_MAJOR: Integer
 
 JSON::VERSION_MINOR: Integer
 
+%a{annotate:rdoc:skip}
+module Kernel
+  private
+
+  # <!--
+  #   rdoc-file=ext/json/lib/json/common.rb
+  #   - j(*objs)
+  # -->
+  # Outputs *objs* to STDOUT as JSON strings in the shortest form, that is in one
+  # line.
+  #
+  def j: (*_ToJson) -> nil
+
+  # <!--
+  #   rdoc-file=ext/json/lib/json/common.rb
+  #   - jj(*objs)
+  # -->
+  # Outputs *objs* to STDOUT as JSON strings in a pretty format, with indentation
+  # and over many lines.
+  #
+  def jj: (*_ToJson) -> nil
+
+  # <!--
+  #   rdoc-file=ext/json/lib/json/common.rb
+  #   - JSON(object, *args)
+  # -->
+  # If *object* is string-like, parse the string and return the parsed result as a
+  # Ruby data structure. Otherwise, generate a JSON text from the Ruby data
+  # structure object and return it.
+  #
+  # The *opts* argument is passed through to generate/parse respectively. See
+  # generate and parse for their documentation.
+  #
+  def JSON: (string source, ?json_options opts) -> untyped
+          | (_ToJson obj, ?json_options opts) -> String
+end
+
 %a{annotate:rdoc:skip}
 class Object
   # Converts this object to a string (calling #to_s), converts
@@ -1243,9 +1296,7 @@ class BigDecimal
   #   rdoc-file=ext/json/lib/json/add/bigdecimal.rb
   #   - json_create(object)
   # -->
-  # Import a JSON Marshalled object.
-  #
-  # method used for JSON marshalling support.
+  # See #as_json.
   #
   def self.json_create: (Hash[String, String] object) -> instance
 
@@ -1253,9 +1304,23 @@ class BigDecimal
   #   rdoc-file=ext/json/lib/json/add/bigdecimal.rb
   #   - as_json(*)
   # -->
-  # Marshal the object to JSON.
+  # Methods `BigDecimal#as_json` and `BigDecimal.json_create` may be used to
+  # serialize and deserialize a BigDecimal object; see
+  # [Marshal](rdoc-ref:Marshal).
+  #
+  # Method `BigDecimal#as_json` serializes `self`, returning a 2-element hash
+  # representing `self`:
   #
-  # method used for JSON marshalling support.
+  #     require 'json/add/bigdecimal'
+  #     x = BigDecimal(2).as_json             # => {"json_class"=>"BigDecimal", "b"=>"27:0.2e1"}
+  #     y = BigDecimal(2.0, 4).as_json        # => {"json_class"=>"BigDecimal", "b"=>"36:0.2e1"}
+  #     z = BigDecimal(Complex(2, 0)).as_json # => {"json_class"=>"BigDecimal", "b"=>"27:0.2e1"}
+  #
+  # Method `JSON.create` deserializes such a hash, returning a BigDecimal object:
+  #
+  #     BigDecimal.json_create(x) # => 0.2e1
+  #     BigDecimal.json_create(y) # => 0.2e1
+  #     BigDecimal.json_create(z) # => 0.2e1
   #
   def as_json: (*untyped) -> Hash[String, String]
 
@@ -1263,7 +1328,18 @@ class BigDecimal
   #   rdoc-file=ext/json/lib/json/add/bigdecimal.rb
   #   - to_json(*args)
   # -->
-  # return the JSON value
+  # Returns a JSON string representing `self`:
+  #
+  #     require 'json/add/bigdecimal'
+  #     puts BigDecimal(2).to_json
+  #     puts BigDecimal(2.0, 4).to_json
+  #     puts BigDecimal(Complex(2, 0)).to_json
+  #
+  # Output:
+  #
+  #     {"json_class":"BigDecimal","b":"27:0.2e1"}
+  #     {"json_class":"BigDecimal","b":"36:0.2e1"}
+  #     {"json_class":"BigDecimal","b":"27:0.2e1"}
   #
   def to_json: (?JSON::State state) -> String
 end
@@ -1274,8 +1350,7 @@ class Complex
   #   rdoc-file=ext/json/lib/json/add/complex.rb
   #   - json_create(object)
   # -->
-  # Deserializes JSON string by converting Real value `r`, imaginary value `i`, to
-  # a Complex object.
+  # See #as_json.
   #
   def self.json_create: (Hash[String, String | Numeric] object) -> instance
 
@@ -1283,8 +1358,20 @@ class Complex
   #   rdoc-file=ext/json/lib/json/add/complex.rb
   #   - as_json(*)
   # -->
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods `Complex#as_json` and `Complex.json_create` may be used to serialize
+  # and deserialize a Complex object; see [Marshal](rdoc-ref:Marshal).
+  #
+  # Method `Complex#as_json` serializes `self`, returning a 2-element hash
+  # representing `self`:
+  #
+  #     require 'json/add/complex'
+  #     x = Complex(2).as_json      # => {"json_class"=>"Complex", "r"=>2, "i"=>0}
+  #     y = Complex(2.0, 4).as_json # => {"json_class"=>"Complex", "r"=>2.0, "i"=>4}
+  #
+  # Method `JSON.create` deserializes such a hash, returning a Complex object:
+  #
+  #     Complex.json_create(x) # => (2+0i)
+  #     Complex.json_create(y) # => (2.0+4i)
   #
   def as_json: (*untyped) -> Hash[String, String | Numeric]
 
@@ -1292,8 +1379,16 @@ class Complex
   #   rdoc-file=ext/json/lib/json/add/complex.rb
   #   - to_json(*args)
   # -->
-  # Stores class name (Complex) along with real value `r` and imaginary value `i`
-  # as JSON string
+  # Returns a JSON string representing `self`:
+  #
+  #     require 'json/add/complex'
+  #     puts Complex(2).to_json
+  #     puts Complex(2.0, 4).to_json
+  #
+  # Output:
+  #
+  #     {"json_class":"Complex","r":2,"i":0}
+  #     {"json_class":"Complex","r":2.0,"i":4}
   #
   def to_json: (?JSON::State state) -> String
 end
@@ -1304,8 +1399,7 @@ class Date
   #   rdoc-file=ext/json/lib/json/add/date.rb
   #   - json_create(object)
   # -->
-  # Deserializes JSON string by converting Julian year `y`, month `m`, day `d` and
-  # Day of Calendar Reform `sg` to Date.
+  # See #as_json.
   #
   def self.json_create: (Hash[String, String | Integer | Float] object) -> instance
 
@@ -1313,8 +1407,20 @@ class Date
   #   rdoc-file=ext/json/lib/json/add/date.rb
   #   - as_json(*)
   # -->
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods `Date#as_json` and `Date.json_create` may be used to serialize and
+  # deserialize a Date object; see [Marshal](rdoc-ref:Marshal).
+  #
+  # Method `Date#as_json` serializes `self`, returning a 2-element hash
+  # representing `self`:
+  #
+  #     require 'json/add/date'
+  #     x = Date.today.as_json
+  #     # => {"json_class"=>"Date", "y"=>2023, "m"=>11, "d"=>21, "sg"=>2299161.0}
+  #
+  # Method `JSON.create` deserializes such a hash, returning a Date object:
+  #
+  #     Date.json_create(x)
+  #     # => #<Date: 2023-11-21 ((2460270j,0s,0n),+0s,2299161j)>
   #
   def as_json: (*untyped) -> Hash[String, String | Integer | Float]
 
@@ -1322,8 +1428,14 @@ class Date
   #   rdoc-file=ext/json/lib/json/add/date.rb
   #   - to_json(*args)
   # -->
-  # Stores class name (Date) with Julian year `y`, month `m`, day `d` and Day of
-  # Calendar Reform `sg` as JSON string
+  # Returns a JSON string representing `self`:
+  #
+  #     require 'json/add/date'
+  #     puts Date.today.to_json
+  #
+  # Output:
+  #
+  #     {"json_class":"Date","y":2023,"m":11,"d":21,"sg":2299161.0}
   #
   def to_json: (?JSON::State state) -> String
 end
@@ -1334,9 +1446,7 @@ class DateTime
   #   rdoc-file=ext/json/lib/json/add/date_time.rb
   #   - json_create(object)
   # -->
-  # Deserializes JSON string by converting year `y`, month `m`, day `d`, hour `H`,
-  # minute `M`, second `S`, offset `of` and Day of Calendar Reform `sg` to
-  # DateTime.
+  # See #as_json.
   #
   def self.json_create: (Hash[String, String | Integer | Float] object) -> instance
 
@@ -1344,8 +1454,19 @@ class DateTime
   #   rdoc-file=ext/json/lib/json/add/date_time.rb
   #   - as_json(*)
   # -->
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods `DateTime#as_json` and `DateTime.json_create` may be used to serialize
+  # and deserialize a DateTime object; see [Marshal](rdoc-ref:Marshal).
+  #
+  # Method `DateTime#as_json` serializes `self`, returning a 2-element hash
+  # representing `self`:
+  #
+  #     require 'json/add/datetime'
+  #     x = DateTime.now.as_json
+  #     # => {"json_class"=>"DateTime", "y"=>2023, "m"=>11, "d"=>21, "sg"=>2299161.0}
+  #
+  # Method `JSON.create` deserializes such a hash, returning a DateTime object:
+  #
+  #     DateTime.json_create(x) # BUG? Raises Date::Error "invalid date"
   #
   def as_json: (*untyped) -> Hash[String, String | Integer | Float]
 
@@ -1353,9 +1474,14 @@ class DateTime
   #   rdoc-file=ext/json/lib/json/add/date_time.rb
   #   - to_json(*args)
   # -->
-  # Stores class name (DateTime) with Julian year `y`, month `m`, day `d`, hour
-  # `H`, minute `M`, second `S`, offset `of` and Day of Calendar Reform `sg` as
-  # JSON string
+  # Returns a JSON string representing `self`:
+  #
+  #     require 'json/add/datetime'
+  #     puts DateTime.now.to_json
+  #
+  # Output:
+  #
+  #     {"json_class":"DateTime","y":2023,"m":11,"d":21,"sg":2299161.0}
   #
   def to_json: (?JSON::State state) -> String
 end
@@ -1366,8 +1492,7 @@ class Exception
   #   rdoc-file=ext/json/lib/json/add/exception.rb
   #   - json_create(object)
   # -->
-  # Deserializes JSON string by constructing new Exception object with message `m`
-  # and backtrace `b` serialized with `to_json`
+  # See #as_json.
   #
   def self.json_create: (Hash[String, String | Array[String] | nil] object) -> instance
 
@@ -1375,8 +1500,18 @@ class Exception
   #   rdoc-file=ext/json/lib/json/add/exception.rb
   #   - as_json(*)
   # -->
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods `Exception#as_json` and `Exception.json_create` may be used to
+  # serialize and deserialize a Exception object; see [Marshal](rdoc-ref:Marshal).
+  #
+  # Method `Exception#as_json` serializes `self`, returning a 2-element hash
+  # representing `self`:
+  #
+  #     require 'json/add/exception'
+  #     x = Exception.new('Foo').as_json # => {"json_class"=>"Exception", "m"=>"Foo", "b"=>nil}
+  #
+  # Method `JSON.create` deserializes such a hash, returning a Exception object:
+  #
+  #     Exception.json_create(x) # => #<Exception: Foo>
   #
   def as_json: (*untyped) -> Hash[String, String | Array[String] | nil]
 
@@ -1384,8 +1519,14 @@ class Exception
   #   rdoc-file=ext/json/lib/json/add/exception.rb
   #   - to_json(*args)
   # -->
-  # Stores class name (Exception) with message `m` and backtrace array `b` as JSON
-  # string
+  # Returns a JSON string representing `self`:
+  #
+  #     require 'json/add/exception'
+  #     puts Exception.new('Foo').to_json
+  #
+  # Output:
+  #
+  #     {"json_class":"Exception","m":"Foo","b":null}
   #
   def to_json: (?JSON::State state) -> String
 end
@@ -1396,8 +1537,7 @@ class OpenStruct
   #   rdoc-file=ext/json/lib/json/add/ostruct.rb
   #   - json_create(object)
   # -->
-  # Deserializes JSON string by constructing new Struct object with values `t`
-  # serialized by `to_json`.
+  # See #as_json.
   #
   def self.json_create: (Hash[String, String | Hash[Symbol, untyped]] object) -> instance
 
@@ -1405,8 +1545,21 @@ class OpenStruct
   #   rdoc-file=ext/json/lib/json/add/ostruct.rb
   #   - as_json(*)
   # -->
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods `OpenStruct#as_json` and `OpenStruct.json_create` may be used to
+  # serialize and deserialize a OpenStruct object; see
+  # [Marshal](rdoc-ref:Marshal).
+  #
+  # Method `OpenStruct#as_json` serializes `self`, returning a 2-element hash
+  # representing `self`:
+  #
+  #     require 'json/add/ostruct'
+  #     x = OpenStruct.new('name' => 'Rowdy', :age => nil).as_json
+  #     # => {"json_class"=>"OpenStruct", "t"=>{:name=>'Rowdy', :age=>nil}}
+  #
+  # Method `JSON.create` deserializes such a hash, returning a OpenStruct object:
+  #
+  #     OpenStruct.json_create(x)
+  #     # => #<OpenStruct name='Rowdy', age=nil>
   #
   def as_json: (*untyped) -> Hash[String, String | Hash[Symbol, untyped]]
 
@@ -1414,7 +1567,14 @@ class OpenStruct
   #   rdoc-file=ext/json/lib/json/add/ostruct.rb
   #   - to_json(*args)
   # -->
-  # Stores class name (OpenStruct) with this struct's values `t` as a JSON string.
+  # Returns a JSON string representing `self`:
+  #
+  #     require 'json/add/ostruct'
+  #     puts OpenStruct.new('name' => 'Rowdy', :age => nil).to_json
+  #
+  # Output:
+  #
+  #     {"json_class":"OpenStruct","t":{'name':'Rowdy',"age":null}}
   #
   def to_json: (?JSON::State state) -> String
 end
@@ -1425,8 +1585,7 @@ class Range[out Elem]
   #   rdoc-file=ext/json/lib/json/add/range.rb
   #   - json_create(object)
   # -->
-  # Deserializes JSON string by constructing new Range object with arguments `a`
-  # serialized by `to_json`.
+  # See #as_json.
   #
   def self.json_create: [A] (Hash[String, String | [ A, A, bool ]] object) -> Range[A]
 
@@ -1434,8 +1593,22 @@ class Range[out Elem]
   #   rdoc-file=ext/json/lib/json/add/range.rb
   #   - as_json(*)
   # -->
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods `Range#as_json` and `Range.json_create` may be used to serialize and
+  # deserialize a Range object; see [Marshal](rdoc-ref:Marshal).
+  #
+  # Method `Range#as_json` serializes `self`, returning a 2-element hash
+  # representing `self`:
+  #
+  #     require 'json/add/range'
+  #     x = (1..4).as_json     # => {"json_class"=>"Range", "a"=>[1, 4, false]}
+  #     y = (1...4).as_json    # => {"json_class"=>"Range", "a"=>[1, 4, true]}
+  #     z = ('a'..'d').as_json # => {"json_class"=>"Range", "a"=>["a", "d", false]}
+  #
+  # Method `JSON.create` deserializes such a hash, returning a Range object:
+  #
+  #     Range.json_create(x) # => 1..4
+  #     Range.json_create(y) # => 1...4
+  #     Range.json_create(z) # => "a".."d"
   #
   def as_json: (*untyped) -> Hash[String, String | [ Elem, Elem, bool ]]
 
@@ -1443,9 +1616,18 @@ class Range[out Elem]
   #   rdoc-file=ext/json/lib/json/add/range.rb
   #   - to_json(*args)
   # -->
-  # Stores class name (Range) with JSON array of arguments `a` which include
-  # `first` (integer), `last` (integer), and `exclude_end?` (boolean) as JSON
-  # string.
+  # Returns a JSON string representing `self`:
+  #
+  #     require 'json/add/range'
+  #     puts (1..4).to_json
+  #     puts (1...4).to_json
+  #     puts ('a'..'d').to_json
+  #
+  # Output:
+  #
+  #     {"json_class":"Range","a":[1,4,false]}
+  #     {"json_class":"Range","a":[1,4,true]}
+  #     {"json_class":"Range","a":["a","d",false]}
   #
   def to_json: (?JSON::State state) -> String
 end
@@ -1456,8 +1638,7 @@ class Rational
   #   rdoc-file=ext/json/lib/json/add/rational.rb
   #   - json_create(object)
   # -->
-  # Deserializes JSON string by converting numerator value `n`, denominator value
-  # `d`, to a Rational object.
+  # See #as_json.
   #
   def self.json_create: (Hash[String, String | Integer] object) -> instance
 
@@ -1465,8 +1646,20 @@ class Rational
   #   rdoc-file=ext/json/lib/json/add/rational.rb
   #   - as_json(*)
   # -->
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods `Rational#as_json` and `Rational.json_create` may be used to serialize
+  # and deserialize a Rational object; see [Marshal](rdoc-ref:Marshal).
+  #
+  # Method `Rational#as_json` serializes `self`, returning a 2-element hash
+  # representing `self`:
+  #
+  #     require 'json/add/rational'
+  #     x = Rational(2, 3).as_json
+  #     # => {"json_class"=>"Rational", "n"=>2, "d"=>3}
+  #
+  # Method `JSON.create` deserializes such a hash, returning a Rational object:
+  #
+  #     Rational.json_create(x)
+  #     # => (2/3)
   #
   def as_json: (*untyped) -> Hash[String, String | Integer]
 
@@ -1474,8 +1667,14 @@ class Rational
   #   rdoc-file=ext/json/lib/json/add/rational.rb
   #   - to_json(*args)
   # -->
-  # Stores class name (Rational) along with numerator value `n` and denominator
-  # value `d` as JSON string
+  # Returns a JSON string representing `self`:
+  #
+  #     require 'json/add/rational'
+  #     puts Rational(2, 3).to_json
+  #
+  # Output:
+  #
+  #     {"json_class":"Rational","n":2,"d":3}
   #
   def to_json: (?JSON::State state) -> String
 end
@@ -1486,8 +1685,7 @@ class Regexp
   #   rdoc-file=ext/json/lib/json/add/regexp.rb
   #   - json_create(object)
   # -->
-  # Deserializes JSON string by constructing new Regexp object with source `s`
-  # (Regexp or String) and options `o` serialized by `to_json`
+  # See #as_json.
   #
   def self.json_create: (Hash[String, String | Integer] object) -> instance
 
@@ -1495,8 +1693,19 @@ class Regexp
   #   rdoc-file=ext/json/lib/json/add/regexp.rb
   #   - as_json(*)
   # -->
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods `Regexp#as_json` and `Regexp.json_create` may be used to serialize and
+  # deserialize a Regexp object; see [Marshal](rdoc-ref:Marshal).
+  #
+  # Method `Regexp#as_json` serializes `self`, returning a 2-element hash
+  # representing `self`:
+  #
+  #     require 'json/add/regexp'
+  #     x = /foo/.as_json
+  #     # => {"json_class"=>"Regexp", "o"=>0, "s"=>"foo"}
+  #
+  # Method `JSON.create` deserializes such a hash, returning a Regexp object:
+  #
+  #     Regexp.json_create(x) # => /foo/
   #
   def as_json: (*untyped) -> Hash[String, String | Integer]
 
@@ -1504,8 +1713,14 @@ class Regexp
   #   rdoc-file=ext/json/lib/json/add/regexp.rb
   #   - to_json(*args)
   # -->
-  # Stores class name (Regexp) with options `o` and source `s` (Regexp or String)
-  # as JSON string
+  # Returns a JSON string representing `self`:
+  #
+  #     require 'json/add/regexp'
+  #     puts /foo/.to_json
+  #
+  # Output:
+  #
+  #     {"json_class":"Regexp","o":0,"s":"foo"}
   #
   def to_json: (?JSON::State state) -> String
 end
@@ -1516,9 +1731,7 @@ class Set[unchecked out A]
   #   rdoc-file=ext/json/lib/json/add/set.rb
   #   - json_create(object)
   # -->
-  # Import a JSON Marshalled object.
-  #
-  # method used for JSON marshalling support.
+  # See #as_json.
   #
   def self.json_create: [A] (Hash[String, String | Array[A]] object) -> Set[A]
 
@@ -1526,9 +1739,19 @@ class Set[unchecked out A]
   #   rdoc-file=ext/json/lib/json/add/set.rb
   #   - as_json(*)
   # -->
-  # Marshal the object to JSON.
+  # Methods `Set#as_json` and `Set.json_create` may be used to serialize and
+  # deserialize a Set object; see [Marshal](rdoc-ref:Marshal).
+  #
+  # Method `Set#as_json` serializes `self`, returning a 2-element hash
+  # representing `self`:
   #
-  # method used for JSON marshalling support.
+  #     require 'json/add/set'
+  #     x = Set.new(%w/foo bar baz/).as_json
+  #     # => {"json_class"=>"Set", "a"=>["foo", "bar", "baz"]}
+  #
+  # Method `JSON.create` deserializes such a hash, returning a Set object:
+  #
+  #     Set.json_create(x) # => #<Set: {"foo", "bar", "baz"}>
   #
   def as_json: (*untyped) -> Hash[String, String | Array[A]]
 
@@ -1536,7 +1759,14 @@ class Set[unchecked out A]
   #   rdoc-file=ext/json/lib/json/add/set.rb
   #   - to_json(*args)
   # -->
-  # return the JSON value
+  # Returns a JSON string representing `self`:
+  #
+  #     require 'json/add/set'
+  #     puts Set.new(%w/foo bar baz/).to_json
+  #
+  # Output:
+  #
+  #     {"json_class":"Set","a":["foo","bar","baz"]}
   #
   def to_json: (?JSON::State state) -> String
 end
@@ -1547,8 +1777,7 @@ class Struct[Elem]
   #   rdoc-file=ext/json/lib/json/add/struct.rb
   #   - json_create(object)
   # -->
-  # Deserializes JSON string by constructing new Struct object with values `v`
-  # serialized by `to_json`.
+  # See #as_json.
   #
   def self.json_create: [Elem] (Hash[String, String | Array[Elem]] object) -> Struct[Elem]
 
@@ -1556,8 +1785,21 @@ class Struct[Elem]
   #   rdoc-file=ext/json/lib/json/add/struct.rb
   #   - as_json(*)
   # -->
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods `Struct#as_json` and `Struct.json_create` may be used to serialize and
+  # deserialize a Struct object; see [Marshal](rdoc-ref:Marshal).
+  #
+  # Method `Struct#as_json` serializes `self`, returning a 2-element hash
+  # representing `self`:
+  #
+  #     require 'json/add/struct'
+  #     Customer = Struct.new('Customer', :name, :address, :zip)
+  #     x = Struct::Customer.new.as_json
+  #     # => {"json_class"=>"Struct::Customer", "v"=>[nil, nil, nil]}
+  #
+  # Method `JSON.create` deserializes such a hash, returning a Struct object:
+  #
+  #     Struct::Customer.json_create(x)
+  #     # => #<struct Struct::Customer name=nil, address=nil, zip=nil>
   #
   def as_json: (*untyped) -> Hash[String, String | Array[Elem]]
 
@@ -1565,8 +1807,15 @@ class Struct[Elem]
   #   rdoc-file=ext/json/lib/json/add/struct.rb
   #   - to_json(*args)
   # -->
-  # Stores class name (Struct) with Struct values `v` as a JSON string. Only named
-  # structs are supported.
+  # Returns a JSON string representing `self`:
+  #
+  #     require 'json/add/struct'
+  #     Customer = Struct.new('Customer', :name, :address, :zip)
+  #     puts Struct::Customer.new.to_json
+  #
+  # Output:
+  #
+  #     {"json_class":"Struct","t":{'name':'Rowdy',"age":null}}
   #
   def to_json: (?JSON::State state) -> String
 end
@@ -1577,8 +1826,7 @@ class Symbol
   #   rdoc-file=ext/json/lib/json/add/symbol.rb
   #   - json_create(o)
   # -->
-  # Deserializes JSON string by converting the `string` value stored in the object
-  # to a Symbol
+  # See #as_json.
   #
   def self.json_create: (Hash[String, String] object) -> instance
 
@@ -1586,8 +1834,19 @@ class Symbol
   #   rdoc-file=ext/json/lib/json/add/symbol.rb
   #   - as_json(*)
   # -->
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods `Symbol#as_json` and `Symbol.json_create` may be used to serialize and
+  # deserialize a Symbol object; see [Marshal](rdoc-ref:Marshal).
+  #
+  # Method `Symbol#as_json` serializes `self`, returning a 2-element hash
+  # representing `self`:
+  #
+  #     require 'json/add/symbol'
+  #     x = :foo.as_json
+  #     # => {"json_class"=>"Symbol", "s"=>"foo"}
+  #
+  # Method `JSON.create` deserializes such a hash, returning a Symbol object:
+  #
+  #     Symbol.json_create(x) # => :foo
   #
   def as_json: (*untyped) -> Hash[String, String]
 
@@ -1595,8 +1854,14 @@ class Symbol
   #   rdoc-file=ext/json/lib/json/add/symbol.rb
   #   - to_json(*a)
   # -->
-  # Stores class name (Symbol) with String representation of Symbol as a JSON
-  # string.
+  # Returns a JSON string representing `self`:
+  #
+  #     require 'json/add/symbol'
+  #     puts :foo.to_json
+  #
+  # Output:
+  #
+  #     # {"json_class":"Symbol","s":"foo"}
   #
   def to_json: (?JSON::State state) -> String
 end
@@ -1607,7 +1872,7 @@ class Time
   #   rdoc-file=ext/json/lib/json/add/time.rb
   #   - json_create(object)
   # -->
-  # Deserializes JSON string by converting time since epoch to Time
+  # See #as_json.
   #
   def self.json_create: (Hash[String, String | Integer] object) -> instance
 
@@ -1615,8 +1880,20 @@ class Time
   #   rdoc-file=ext/json/lib/json/add/time.rb
   #   - as_json(*)
   # -->
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods `Time#as_json` and `Time.json_create` may be used to serialize and
+  # deserialize a Time object; see [Marshal](rdoc-ref:Marshal).
+  #
+  # Method `Time#as_json` serializes `self`, returning a 2-element hash
+  # representing `self`:
+  #
+  #     require 'json/add/time'
+  #     x = Time.now.as_json
+  #     # => {"json_class"=>"Time", "s"=>1700931656, "n"=>472846644}
+  #
+  # Method `JSON.create` deserializes such a hash, returning a Time object:
+  #
+  #     Time.json_create(x)
+  #     # => 2023-11-25 11:00:56.472846644 -0600
   #
   def as_json: (*untyped) -> Hash[String, String | Integer]
 
@@ -1624,8 +1901,14 @@ class Time
   #   rdoc-file=ext/json/lib/json/add/time.rb
   #   - to_json(*args)
   # -->
-  # Stores class name (Time) with number of seconds since epoch and number of
-  # microseconds for Time as JSON string
+  # Returns a JSON string representing `self`:
+  #
+  #     require 'json/add/time'
+  #     puts Time.now.to_json
+  #
+  # Output:
+  #
+  #     {"json_class":"Time","s":1700931678,"n":980650786}
   #
   def to_json: (?JSON::State state) -> String
 end