rbs 3.9.4 → 4.1.1

data/stdlib/json/0/json.rbs

@@ -1,5 +1,5 @@
 interface _ToJson
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 # <!-- rdoc-file=ext/json/lib/json/common.rb -->
@@ -14,9 +14,6 @@ end
 class JSON::GeneratorError < JSON::JSONError
 end
 
-class JSON::UnparserError < JSON::GeneratorError
-end
-
 # <!-- rdoc-file=ext/json/lib/json/common.rb -->
 # This exception is raised if a parser error occurs.
 #
@@ -82,8 +79,8 @@ end
 # JSON is a lightweight data-interchange format.
 #
 # A JSON value is one of the following:
-# *   Double-quoted text:  `"foo"`.
-# *   Number:  `1`, `1.0`, `2.0e2`.
+# *   Double-quoted text:  <code>"foo"</code>.
+# *   Number:  `1`, <code>1.0</code>, <code>2.0e2</code>.
 # *   Boolean:  `true`, `false`.
 # *   Null: `null`.
 # *   Array: an ordered list of values, enclosed by square brackets:
@@ -108,8 +105,8 @@ end
 # ### Parsing JSON
 #
 # You can parse a String containing JSON data using either of two methods:
-# *   `JSON.parse(source, opts)`
-# *   `JSON.parse!(source, opts)`
+# *   <code>JSON.parse(source, opts)</code>
+# *   <code>JSON.parse!(source, opts)</code>
 #
 # where
 # *   `source` is a Ruby object.
@@ -202,6 +199,24 @@ end
 #
 # ---
 #
+# Option `allow_duplicate_key` specifies whether duplicate keys in objects
+# should be ignored or cause an error to be raised:
+#
+# When not specified:
+#     # The last value is used and a deprecation warning emitted.
+#     JSON.parse('{"a": 1, "a":2}') => {"a" => 2}
+#     # warning: detected duplicate keys in JSON object.
+#     # This will raise an error in json 3.0 unless enabled via `allow_duplicate_key: true`
+#
+# When set to ``true``
+#     # The last value is used.
+#     JSON.parse('{"a": 1, "a":2}') => {"a" => 2}
+#
+# When set to ``false``, the future default:
+#     JSON.parse('{"a": 1, "a":2}') => duplicate key at line 1 column 1 (JSON::ParserError)
+#
+# ---
+#
 # Option `allow_nan` (boolean) specifies whether to allow NaN, Infinity, and
 # MinusInfinity in `source`; defaults to `false`.
 #
@@ -218,8 +233,22 @@ end
 #     ruby = JSON.parse(source, {allow_nan: true})
 #     ruby # => [NaN, Infinity, -Infinity]
 #
+# ---
+#
+# Option `allow_trailing_comma` (boolean) specifies whether to allow trailing
+# commas in objects and arrays; defaults to `false`.
+#
+# With the default, `false`:
+#     JSON.parse('[1,]') # unexpected character: ']' at line 1 column 4 (JSON::ParserError)
+#
+# When enabled:
+#     JSON.parse('[1,]', allow_trailing_comma: true) # => [1]
+#
 # ###### Output Options
 #
+# Option `freeze` (boolean) specifies whether the returned objects will be
+# frozen; defaults to `false`.
+#
 # Option `symbolize_names` (boolean) specifies whether returned Hash keys should
 # be Symbols; defaults to `false` (use Strings).
 #
@@ -263,12 +292,12 @@ end
 # ---
 #
 # Option `create_additions` (boolean) specifies whether to use JSON additions in
-# parsing. See [\JSON Additions](#module-JSON-label-JSON+Additions).
+# parsing. See [JSON Additions](#module-JSON-label-JSON+Additions).
 #
 # ### Generating JSON
 #
 # To generate a Ruby String containing JSON data, use method
-# `JSON.generate(source, opts)`, where
+# <code>JSON.generate(source, opts)</code>, where
 # *   `source` is a Ruby object.
 # *   `opts` is a Hash object containing options that control both input allowed
 #     and output formatting.
@@ -332,7 +361,7 @@ end
 # ###### Input Options
 #
 # Option `allow_nan` (boolean) specifies whether `NaN`, `Infinity`, and
-# `-Infinity` may be generated; defaults to `false`.
+# <code>-Infinity</code> may be generated; defaults to `false`.
 #
 # With the default, `false`:
 #     # Raises JSON::GeneratorError (920: NaN not allowed in JSON):
@@ -348,6 +377,25 @@ end
 #
 # ---
 #
+# Option `allow_duplicate_key` (boolean) specifies whether hashes with duplicate
+# keys should be allowed or produce an error. defaults to emit a deprecation
+# warning.
+#
+# With the default, (not set):
+#     Warning[:deprecated] = true
+#     JSON.generate({ foo: 1, "foo" => 2 })
+#     # warning: detected duplicate key "foo" in {foo: 1, "foo" => 2}.
+#     # This will raise an error in json 3.0 unless enabled via `allow_duplicate_key: true`
+#     # => '{"foo":1,"foo":2}'
+#
+# With `false`
+#     JSON.generate({ foo: 1, "foo" => 2 }, allow_duplicate_key: false)
+#     # detected duplicate key "foo" in {foo: 1, "foo" => 2} (JSON::GeneratorError)
+#
+# In version 3.0, `false` will become the default.
+#
+# ---
+#
 # Option `max_nesting` (Integer) specifies the maximum nesting depth in `obj`;
 # defaults to `100`.
 #
@@ -361,9 +409,9 @@ end
 #
 # ###### 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 `script_safe` (boolean) specifies wether <code>'\u2028'</code>,
+# <code>'\u2029'</code> and <code>'/'</code> 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.
@@ -377,19 +425,21 @@ end
 # format, using whitespace. See also JSON.pretty_generate.
 #
 # *   Option `array_nl` (String) specifies a string (usually a newline) to be
-#     inserted after each JSON array; defaults to the empty String, `''`.
+#     inserted after each JSON array; defaults to the empty String,
+#     <code>''</code>.
 # *   Option `object_nl` (String) specifies a string (usually a newline) to be
-#     inserted after each JSON object; defaults to the empty String, `''`.
+#     inserted after each JSON object; defaults to the empty String,
+#     <code>''</code>.
 # *   Option `indent` (String) specifies the string (usually spaces) to be used
-#     for indentation; defaults to the empty String, `''`; defaults to the empty
-#     String, `''`; has no effect unless options `array_nl` or `object_nl`
-#     specify newlines.
+#     for indentation; defaults to the empty String, <code>''</code>; defaults
+#     to the empty String, <code>''</code>; has no effect unless options
+#     `array_nl` or `object_nl` specify newlines.
 # *   Option `space` (String) specifies a string (usually a space) to be
 #     inserted after the colon in each JSON object's pair; defaults to the empty
-#     String, `''`.
+#     String, <code>''</code>.
 # *   Option `space_before` (String) specifies a string (usually a space) to be
 #     inserted before the colon in each JSON object's pair; defaults to the
-#     empty String, `''`.
+#     empty String, <code>''</code>.
 #
 # In this example, `obj` is used first to generate the shortest JSON data (no
 # whitespace), then again with all formatting options specified:
@@ -423,6 +473,9 @@ end
 #
 # ## JSON Additions
 #
+# Note that JSON Additions must only be used with trusted data, and is
+# deprecated.
+#
 # When you "round trip" a non-String object from Ruby to JSON and back, you have
 # a new String, instead of the object you began with:
 #     ruby0 = Range.new(0, 2)
@@ -468,26 +521,26 @@ end
 #       With addition:     0..2 (Range)
 #
 # The JSON module includes additions for certain classes. You can also craft
-# custom additions. See [Custom \JSON
+# custom additions. See [Custom JSON
 # Additions](#module-JSON-label-Custom+JSON+Additions).
 #
 # ### Built-in Additions
 #
 # The JSON module includes additions for certain classes. To use an addition,
 # `require` its source:
-# *   BigDecimal: `require 'json/add/bigdecimal'`
-# *   Complex: `require 'json/add/complex'`
-# *   Date: `require 'json/add/date'`
-# *   DateTime: `require 'json/add/date_time'`
-# *   Exception: `require 'json/add/exception'`
-# *   OpenStruct: `require 'json/add/ostruct'`
-# *   Range: `require 'json/add/range'`
-# *   Rational: `require 'json/add/rational'`
-# *   Regexp: `require 'json/add/regexp'`
-# *   Set: `require 'json/add/set'`
-# *   Struct: `require 'json/add/struct'`
-# *   Symbol: `require 'json/add/symbol'`
-# *   Time: `require 'json/add/time'`
+# *   BigDecimal: <code>require 'json/add/bigdecimal'</code>
+# *   Complex: <code>require 'json/add/complex'</code>
+# *   Date: <code>require 'json/add/date'</code>
+# *   DateTime: <code>require 'json/add/date_time'</code>
+# *   Exception: <code>require 'json/add/exception'</code>
+# *   OpenStruct: <code>require 'json/add/ostruct'</code>
+# *   Range: <code>require 'json/add/range'</code>
+# *   Rational: <code>require 'json/add/rational'</code>
+# *   Regexp: <code>require 'json/add/regexp'</code>
+# *   Set: <code>require 'json/add/set'</code>
+# *   Struct: <code>require 'json/add/struct'</code>
+# *   Symbol: <code>require 'json/add/symbol'</code>
+# *   Time: <code>require 'json/add/time'</code>
 #
 # To reduce punctuation clutter, the examples below show the generated JSON via
 # `puts`, rather than the usual `inspect`,
@@ -711,8 +764,6 @@ module JSON
   #
   def self.create_id=: (_ToS create_id) -> _ToS
 
-  def self.deep_const_get: (interned path) -> untyped
-
   # <!--
   #   rdoc-file=ext/json/lib/json/common.rb
   #   - JSON.dump(obj, io = nil, limit = nil)
@@ -754,6 +805,7 @@ module JSON
   #     opts = JSON.dump_default_options
   #     opts # => {:max_nesting=>false, :allow_nan=>true}
   #
+  %a{deprecated}
   def self.dump_default_options: () -> options
 
   # <!-- rdoc-file=ext/json/lib/json/common.rb -->
@@ -761,6 +813,7 @@ module JSON
   #     opts = JSON.dump_default_options
   #     opts # => {:max_nesting=>false, :allow_nan=>true}
   #
+  %a{deprecated}
   def self.dump_default_options=: (options) -> options
 
   # <!--
@@ -778,19 +831,16 @@ module JSON
   #     # Raises SystemStackError (stack level too deep):
   #     JSON.fast_generate(a)
   #
+  %a{deprecated}
   def self?.fast_generate: (_ToJson obj, ?options opts) -> String
 
-  alias self.fast_unparse self.fast_generate
-
-  alias fast_unparse fast_generate
-
   # <!--
   #   rdoc-file=ext/json/lib/json/common.rb
   #   - JSON.generate(obj, opts = nil) -> new_string
   # -->
   # Returns a String containing the generated JSON data.
   #
-  # See also JSON.fast_generate, JSON.pretty_generate.
+  # See also JSON.pretty_generate.
   #
   # Argument `obj` is the Ruby object to be converted to JSON.
   #
@@ -809,7 +859,7 @@ module JSON
   #     json = JSON.generate(obj)
   #     json # => '{"foo":0,"bar":"s","baz":"bat"}'
   #
-  # For examples of generating from other Ruby objects, see [Generating \JSON from
+  # For examples of generating from other Ruby objects, see [Generating JSON from
   # Other Objects](#module-JSON-label-Generating+JSON+from+Other+Objects).
   #
   # ---
@@ -832,14 +882,7 @@ module JSON
 
   # <!--
   #   rdoc-file=ext/json/lib/json/common.rb
-  #   - iconv(to, from, string)
-  # -->
-  # Encodes string using String.encode.
-  #
-  def self.iconv: (encoding to, encoding from, String string) -> String
-
-  # <!--
-  #   rdoc-file=ext/json/lib/json/common.rb
+  #   - JSON.load(source, options = {}) -> object
   #   - JSON.load(source, proc = nil, options = {}) -> object
   # -->
   # Returns the Ruby objects created by parsing the given `source`.
@@ -854,15 +897,17 @@ module JSON
   # 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.
-  #     *   If `source` responds to instance method `to_io`, `source.to_io.read`
-  #         becomes the source.
-  #     *   If `source` responds to instance method `read`, `source.read` becomes
-  #         the source.
-  #     *   If both of the following are true, source becomes the String `'null'`:
+  #     *   If `source` responds to instance method `to_str`,
+  #         <code>source.to_str</code> becomes the source.
+  #     *   If `source` responds to instance method `to_io`,
+  #         <code>source.to_io.read</code> becomes the source.
+  #     *   If `source` responds to instance method `read`,
+  #         <code>source.read</code> becomes the source.
+  #     *   If both of the following are true, source becomes the String
+  #         <code>'null'</code>:
   #         *   Option `allow_blank` specifies a truthy value.
-  #         *   The source, as defined above, is `nil` or the empty String `''`.
+  #         *   The source, as defined above, is `nil` or the empty String
+  #             <code>''</code>.
   #     *   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
@@ -874,7 +919,7 @@ module JSON
   # ---
   #
   # When no `proc` is given, modifies `source` as above and returns the result of
-  # `parse(source, opts)`;  see #parse.
+  # <code>parse(source, opts)</code>;  see #parse.
   #
   # Source for following examples:
   #     source = <<~JSON
@@ -909,8 +954,8 @@ module JSON
   #
   # When `proc` is given:
   # *   Modifies `source` as above.
-  # *   Gets the `result` from calling `parse(source, opts)`.
-  # *   Recursively calls `proc(result)`.
+  # *   Gets the `result` from calling <code>parse(source, opts)</code>.
+  # *   Recursively calls <code>proc(result)</code>.
   # *   Returns the final result.
   #
   # Example:
@@ -952,6 +997,7 @@ module JSON
   #       when Array
   #         obj.map! {|v| deserialize_obj v }
   #       end
+  #       obj
   #     })
   #     pp ruby
   #
@@ -974,7 +1020,8 @@ module JSON
   #        #<Admin:0x00000000064c41f8
   #        @attributes={"type"=>"Admin", "password"=>"0wn3d"}>}
   #
-  def self?.load: (string | _ReadableIO | _Read source, ?Proc proc, ?options options) -> untyped
+  def self?.load: (string | _ReadableIO | _Read source, ?options options) -> untyped
+                | [T] (string | _ReadableIO | _Read source, ^(?) -> T, ?options options) -> T
 
   # <!--
   #   rdoc-file=ext/json/lib/json/common.rb
@@ -1003,6 +1050,7 @@ module JSON
   #     opts = JSON.load_default_options
   #     opts # => {:max_nesting=>false, :allow_nan=>true, :allow_blank=>true, :create_additions=>true}
   #
+  %a{deprecated}
   def self.load_default_options: () -> options
 
   # <!-- rdoc-file=ext/json/lib/json/common.rb -->
@@ -1010,6 +1058,7 @@ module JSON
   #     opts = JSON.load_default_options
   #     opts # => {:max_nesting=>false, :allow_nan=>true, :allow_blank=>true, :create_additions=>true}
   #
+  %a{deprecated}
   def self.load_default_options=: (options) -> options
 
   # <!--
@@ -1038,7 +1087,7 @@ module JSON
   #     ruby.class # => Hash
   #
   # For examples of parsing for all JSON data types, see [Parsing
-  # \JSON](#module-JSON-label-Parsing+JSON).
+  # JSON](#module-JSON-label-Parsing+JSON).
   #
   # Parses nested JSON objects:
   #     source = <<~JSON
@@ -1120,29 +1169,6 @@ module JSON
   #
   def self?.pretty_generate: (_ToJson obj, ?options opts) -> untyped
 
-  alias self.pretty_unparse self.pretty_generate
-
-  alias pretty_unparse pretty_generate
-
-  # Recursively calls passed *Proc* if the parsed data structure is an *Array* or
-  # *Hash*
-  #
-  def self?.recurse_proc: (untyped result) { (*untyped) -> void } -> void
-
-  # <!--
-  #   rdoc-file=ext/json/lib/json/common.rb
-  #   - restore(source, proc = nil, options = nil)
-  # -->
-  #
-  alias self.restore self.load
-
-  # <!--
-  #   rdoc-file=ext/json/lib/json/common.rb
-  #   - 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.
   #
@@ -1152,10 +1178,6 @@ module JSON
   # Sets or Returns the JSON generator state class that is used by JSON.
   #
   def self.state=: (state) -> state
-
-  alias self.unparse self.generate
-
-  alias unparse generate
 end
 
 JSON::FAST_STATE_PROTOTYPE: JSON::state
@@ -1193,6 +1215,7 @@ module Kernel
   # Outputs *objs* to STDOUT as JSON strings in the shortest form, that is in one
   # line.
   #
+  %a{deprecated}
   def j: (*_ToJson) -> nil
 
   # <!--
@@ -1202,11 +1225,12 @@ module Kernel
   # Outputs *objs* to STDOUT as JSON strings in a pretty format, with indentation
   # and over many lines.
   #
+  %a{deprecated}
   def jj: (*_ToJson) -> nil
 
   # <!--
   #   rdoc-file=ext/json/lib/json/common.rb
-  #   - JSON(object, *args)
+  #   - JSON(object, opts = nil)
   # -->
   # 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
@@ -1225,28 +1249,28 @@ class Object
   # it to a JSON string, and returns the result. This is a fallback, if no
   # special method #to_json was defined for some object.
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
 class NilClass
   # Returns a JSON string for nil: 'null'.
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
 class TrueClass
   # Returns a JSON string for true: 'true'.
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
 class FalseClass
   # Returns a JSON string for false: 'false'.
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
@@ -1255,21 +1279,21 @@ class String
   # returns a JSON string encoded with UTF16 big endian characters as
   # \u????.
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
 class Integer
   # Returns a JSON string representation for this Integer number.
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
 class Float
   # Returns a JSON string representation for this Float number.
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
@@ -1279,17 +1303,17 @@ class Hash[unchecked out K, unchecked out V]
   # _state_ is a JSON::State object, that can also be used to configure the
   # produced JSON string output further.
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
-class Array[unchecked out Elem]
+class Array[unchecked out E]
   # Returns a JSON string containing a JSON array, that is generated from
   # this Array instance.
   # _state_ is a JSON::State object, that can also be used to configure the
   # produced JSON string output further.
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
@@ -1306,19 +1330,20 @@ class BigDecimal
   #   rdoc-file=ext/json/lib/json/add/bigdecimal.rb
   #   - as_json(*)
   # -->
-  # Methods `BigDecimal#as_json` and `BigDecimal.json_create` may be used to
-  # serialize and deserialize a BigDecimal object; see
-  # [Marshal](rdoc-ref:Marshal).
+  # Methods <code>BigDecimal#as_json</code> and
+  # <code>BigDecimal.json_create</code> 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 <code>BigDecimal#as_json</code> serializes `self`, returning a
+  # 2-element hash representing `self`:
   #
   #     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:
+  # Method <code>JSON.create</code> deserializes such a hash, returning a
+  # BigDecimal object:
   #
   #     BigDecimal.json_create(x) # => 0.2e1
   #     BigDecimal.json_create(y) # => 0.2e1
@@ -1343,7 +1368,7 @@ class BigDecimal
   #     {"json_class":"BigDecimal","b":"36:0.2e1"}
   #     {"json_class":"BigDecimal","b":"27:0.2e1"}
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
@@ -1360,17 +1385,19 @@ class Complex
   #   rdoc-file=ext/json/lib/json/add/complex.rb
   #   - as_json(*)
   # -->
-  # Methods `Complex#as_json` and `Complex.json_create` may be used to serialize
-  # and deserialize a Complex object; see [Marshal](rdoc-ref:Marshal).
+  # Methods <code>Complex#as_json</code> and <code>Complex.json_create</code> 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`:
+  # Method <code>Complex#as_json</code> 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:
+  # Method <code>JSON.create</code> deserializes such a hash, returning a Complex
+  # object:
   #
   #     Complex.json_create(x) # => (2+0i)
   #     Complex.json_create(y) # => (2.0+4i)
@@ -1392,7 +1419,7 @@ class Complex
   #     {"json_class":"Complex","r":2,"i":0}
   #     {"json_class":"Complex","r":2.0,"i":4}
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
@@ -1409,17 +1436,19 @@ class Date
   #   rdoc-file=ext/json/lib/json/add/date.rb
   #   - as_json(*)
   # -->
-  # Methods `Date#as_json` and `Date.json_create` may be used to serialize and
-  # deserialize a Date object; see [Marshal](rdoc-ref:Marshal).
+  # Methods <code>Date#as_json</code> and <code>Date.json_create</code> 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
+  # Method <code>Date#as_json</code> 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:
+  # Method <code>JSON.create</code> deserializes such a hash, returning a Date
+  # object:
   #
   #     Date.json_create(x)
   #     # => #<Date: 2023-11-21 ((2460270j,0s,0n),+0s,2299161j)>
@@ -1439,7 +1468,7 @@ class Date
   #
   #     {"json_class":"Date","y":2023,"m":11,"d":21,"sg":2299161.0}
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
@@ -1456,17 +1485,19 @@ class DateTime
   #   rdoc-file=ext/json/lib/json/add/date_time.rb
   #   - as_json(*)
   # -->
-  # Methods `DateTime#as_json` and `DateTime.json_create` may be used to serialize
-  # and deserialize a DateTime object; see [Marshal](rdoc-ref:Marshal).
+  # Methods <code>DateTime#as_json</code> and <code>DateTime.json_create</code>
+  # 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`:
+  # Method <code>DateTime#as_json</code> 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:
+  # Method <code>JSON.create</code> deserializes such a hash, returning a DateTime
+  # object:
   #
   #     DateTime.json_create(x) # BUG? Raises Date::Error "invalid date"
   #
@@ -1485,7 +1516,7 @@ class DateTime
   #
   #     {"json_class":"DateTime","y":2023,"m":11,"d":21,"sg":2299161.0}
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
@@ -1502,16 +1533,18 @@ class Exception
   #   rdoc-file=ext/json/lib/json/add/exception.rb
   #   - as_json(*)
   # -->
-  # Methods `Exception#as_json` and `Exception.json_create` may be used to
-  # serialize and deserialize a Exception object; see [Marshal](rdoc-ref:Marshal).
+  # Methods <code>Exception#as_json</code> and <code>Exception.json_create</code>
+  # 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`:
+  # Method <code>Exception#as_json</code> 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:
+  # Method <code>JSON.create</code> deserializes such a hash, returning a
+  # Exception object:
   #
   #     Exception.json_create(x) # => #<Exception: Foo>
   #
@@ -1530,7 +1563,7 @@ class Exception
   #
   #     {"json_class":"Exception","m":"Foo","b":null}
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
@@ -1547,18 +1580,19 @@ class OpenStruct
   #   rdoc-file=ext/json/lib/json/add/ostruct.rb
   #   - as_json(*)
   # -->
-  # Methods `OpenStruct#as_json` and `OpenStruct.json_create` may be used to
-  # serialize and deserialize a OpenStruct object; see
-  # [Marshal](rdoc-ref:Marshal).
+  # Methods <code>OpenStruct#as_json</code> and
+  # <code>OpenStruct.json_create</code> 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`:
+  # Method <code>OpenStruct#as_json</code> 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:
+  # Method <code>JSON.create</code> deserializes such a hash, returning a
+  # OpenStruct object:
   #
   #     OpenStruct.json_create(x)
   #     # => #<OpenStruct name='Rowdy', age=nil>
@@ -1578,11 +1612,11 @@ class OpenStruct
   #
   #     {"json_class":"OpenStruct","t":{'name':'Rowdy',"age":null}}
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
-class Range[out Elem]
+class Range[out E]
   # <!--
   #   rdoc-file=ext/json/lib/json/add/range.rb
   #   - json_create(object)
@@ -1595,24 +1629,26 @@ class Range[out Elem]
   #   rdoc-file=ext/json/lib/json/add/range.rb
   #   - as_json(*)
   # -->
-  # Methods `Range#as_json` and `Range.json_create` may be used to serialize and
-  # deserialize a Range object; see [Marshal](rdoc-ref:Marshal).
+  # Methods <code>Range#as_json</code> and <code>Range.json_create</code> 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`:
+  # Method <code>Range#as_json</code> 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:
+  # Method <code>JSON.create</code> 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 ]]
+  def as_json: (*untyped) -> Hash[String, String | [ E, E, bool ]]
 
   # <!--
   #   rdoc-file=ext/json/lib/json/add/range.rb
@@ -1631,7 +1667,7 @@ class Range[out Elem]
   #     {"json_class":"Range","a":[1,4,true]}
   #     {"json_class":"Range","a":["a","d",false]}
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
@@ -1648,17 +1684,19 @@ class Rational
   #   rdoc-file=ext/json/lib/json/add/rational.rb
   #   - as_json(*)
   # -->
-  # Methods `Rational#as_json` and `Rational.json_create` may be used to serialize
-  # and deserialize a Rational object; see [Marshal](rdoc-ref:Marshal).
+  # Methods <code>Rational#as_json</code> and <code>Rational.json_create</code>
+  # 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`:
+  # Method <code>Rational#as_json</code> 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:
+  # Method <code>JSON.create</code> deserializes such a hash, returning a Rational
+  # object:
   #
   #     Rational.json_create(x)
   #     # => (2/3)
@@ -1678,7 +1716,7 @@ class Rational
   #
   #     {"json_class":"Rational","n":2,"d":3}
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
@@ -1695,17 +1733,19 @@ class Regexp
   #   rdoc-file=ext/json/lib/json/add/regexp.rb
   #   - as_json(*)
   # -->
-  # Methods `Regexp#as_json` and `Regexp.json_create` may be used to serialize and
-  # deserialize a Regexp object; see [Marshal](rdoc-ref:Marshal).
+  # Methods <code>Regexp#as_json</code> and <code>Regexp.json_create</code> 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`:
+  # Method <code>Regexp#as_json</code> 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:
+  # Method <code>JSON.create</code> deserializes such a hash, returning a Regexp
+  # object:
   #
   #     Regexp.json_create(x) # => /foo/
   #
@@ -1724,7 +1764,7 @@ class Regexp
   #
   #     {"json_class":"Regexp","o":0,"s":"foo"}
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
@@ -1741,17 +1781,18 @@ class Set[unchecked out A]
   #   rdoc-file=ext/json/lib/json/add/set.rb
   #   - as_json(*)
   # -->
-  # Methods `Set#as_json` and `Set.json_create` may be used to serialize and
-  # deserialize a Set object; see [Marshal](rdoc-ref:Marshal).
+  # Methods <code>Set#as_json</code> and <code>Set.json_create</code> 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
+  # Method <code>Set#as_json</code> serializes `self`, returning a 2-element hash
   # representing `self`:
   #
   #     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:
+  # Method <code>JSON.create</code> deserializes such a hash, returning a Set
+  # object:
   #
   #     Set.json_create(x) # => #<Set: {"foo", "bar", "baz"}>
   #
@@ -1770,40 +1811,42 @@ class Set[unchecked out A]
   #
   #     {"json_class":"Set","a":["foo","bar","baz"]}
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
-class Struct[Elem]
+class Struct[E]
   # <!--
   #   rdoc-file=ext/json/lib/json/add/struct.rb
   #   - json_create(object)
   # -->
   # See #as_json.
   #
-  def self.json_create: [Elem] (Hash[String, String | Array[Elem]] object) -> Struct[Elem]
+  def self.json_create: [E] (Hash[String, String | Array[E]] object) -> Struct[E]
 
   # <!--
   #   rdoc-file=ext/json/lib/json/add/struct.rb
   #   - as_json(*)
   # -->
-  # Methods `Struct#as_json` and `Struct.json_create` may be used to serialize and
-  # deserialize a Struct object; see [Marshal](rdoc-ref:Marshal).
+  # Methods <code>Struct#as_json</code> and <code>Struct.json_create</code> 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`:
+  # Method <code>Struct#as_json</code> 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:
+  # Method <code>JSON.create</code> 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]]
+  def as_json: (*untyped) -> Hash[String, String | Array[E]]
 
   # <!--
   #   rdoc-file=ext/json/lib/json/add/struct.rb
@@ -1819,7 +1862,7 @@ class Struct[Elem]
   #
   #     {"json_class":"Struct","t":{'name':'Rowdy',"age":null}}
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
@@ -1836,17 +1879,19 @@ class Symbol
   #   rdoc-file=ext/json/lib/json/add/symbol.rb
   #   - as_json(*)
   # -->
-  # Methods `Symbol#as_json` and `Symbol.json_create` may be used to serialize and
-  # deserialize a Symbol object; see [Marshal](rdoc-ref:Marshal).
+  # Methods <code>Symbol#as_json</code> and <code>Symbol.json_create</code> 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`:
+  # Method <code>Symbol#as_json</code> 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:
+  # Method <code>JSON.create</code> deserializes such a hash, returning a Symbol
+  # object:
   #
   #     Symbol.json_create(x) # => :foo
   #
@@ -1854,7 +1899,7 @@ class Symbol
 
   # <!--
   #   rdoc-file=ext/json/lib/json/add/symbol.rb
-  #   - to_json(*a)
+  #   - to_json(state = nil, *a)
   # -->
   # Returns a JSON string representing `self`:
   #
@@ -1865,7 +1910,7 @@ class Symbol
   #
   #     # {"json_class":"Symbol","s":"foo"}
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end
 
 %a{annotate:rdoc:skip}
@@ -1882,17 +1927,19 @@ class Time
   #   rdoc-file=ext/json/lib/json/add/time.rb
   #   - as_json(*)
   # -->
-  # Methods `Time#as_json` and `Time.json_create` may be used to serialize and
-  # deserialize a Time object; see [Marshal](rdoc-ref:Marshal).
+  # Methods <code>Time#as_json</code> and <code>Time.json_create</code> 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
+  # Method <code>Time#as_json</code> 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:
+  # Method <code>JSON.create</code> deserializes such a hash, returning a Time
+  # object:
   #
   #     Time.json_create(x)
   #     # => 2023-11-25 11:00:56.472846644 -0600
@@ -1912,5 +1959,5 @@ class Time
   #
   #     {"json_class":"Time","s":1700931678,"n":980650786}
   #
-  def to_json: (?JSON::State state) -> String
+  def to_json: (?JSON::State? state) -> String
 end