json 2.6.3 → 2.11.3

data/ext/json/ext/vendor/jeaiii-ltoa.h

@@ -0,0 +1,267 @@
+/*
+
+This file is released under the terms of the MIT License. It is based on the
+work of James Edward Anhalt III, with the original license listed below.
+
+MIT License
+
+Copyright (c) 2024,2025 Enrico Thierbach - https://github.com/radiospiel
+Copyright (c) 2022 James Edward Anhalt III - https://github.com/jeaiii/itoa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+
+#ifndef JEAIII_TO_TEXT_H_
+#define JEAIII_TO_TEXT_H_
+
+#include <stdint.h>
+
+typedef uint_fast32_t u32_t;
+typedef uint_fast64_t u64_t;
+
+#define u32(x) ((u32_t)(x))
+#define u64(x) ((u64_t)(x))
+
+struct digit_pair
+{
+    char dd[2];
+};
+
+static const struct digit_pair *digits_dd = (struct digit_pair *)(
+    "00" "01" "02" "03" "04" "05" "06" "07" "08" "09"
+    "10" "11" "12" "13" "14" "15" "16" "17" "18" "19"
+    "20" "21" "22" "23" "24" "25" "26" "27" "28" "29"
+    "30" "31" "32" "33" "34" "35" "36" "37" "38" "39"
+    "40" "41" "42" "43" "44" "45" "46" "47" "48" "49"
+    "50" "51" "52" "53" "54" "55" "56" "57" "58" "59"
+    "60" "61" "62" "63" "64" "65" "66" "67" "68" "69"
+    "70" "71" "72" "73" "74" "75" "76" "77" "78" "79"
+    "80" "81" "82" "83" "84" "85" "86" "87" "88" "89"
+    "90" "91" "92" "93" "94" "95" "96" "97" "98" "99"
+);
+
+static const struct digit_pair *digits_fd = (struct digit_pair *)(
+    "0_" "1_" "2_" "3_" "4_" "5_" "6_" "7_" "8_" "9_"
+    "10" "11" "12" "13" "14" "15" "16" "17" "18" "19"
+    "20" "21" "22" "23" "24" "25" "26" "27" "28" "29"
+    "30" "31" "32" "33" "34" "35" "36" "37" "38" "39"
+    "40" "41" "42" "43" "44" "45" "46" "47" "48" "49"
+    "50" "51" "52" "53" "54" "55" "56" "57" "58" "59"
+    "60" "61" "62" "63" "64" "65" "66" "67" "68" "69"
+    "70" "71" "72" "73" "74" "75" "76" "77" "78" "79"
+    "80" "81" "82" "83" "84" "85" "86" "87" "88" "89"
+    "90" "91" "92" "93" "94" "95" "96" "97" "98" "99"
+);
+
+static const u64_t mask24 = (u64(1) << 24) - 1;
+static const u64_t mask32 = (u64(1) << 32) - 1;
+static const u64_t mask57 = (u64(1) << 57) - 1;
+
+#define COPY(buffer, digits) memcpy(buffer, &(digits), sizeof(struct digit_pair))
+
+static char *
+jeaiii_ultoa(char *b, u64_t n)
+{
+    if (n < u32(1e2)) {
+        COPY(b, digits_fd[n]);
+        return n < 10 ? b + 1 : b + 2;
+    }
+
+    if (n < u32(1e6)) {
+        if (n < u32(1e4)) {
+            u32_t f0 = u32((10 * (1 << 24) / 1e3 + 1) * n);
+            COPY(b, digits_fd[f0 >> 24]);
+
+            b -= n < u32(1e3);
+            u32_t f2 = (f0 & mask24) * 100;
+            COPY(b + 2, digits_dd[f2 >> 24]);
+
+            return b + 4;
+        }
+
+        u64_t f0 = u64(10 * (1ull << 32ull)/ 1e5 + 1) * n;
+        COPY(b, digits_fd[f0 >> 32]);
+
+        b -= n < u32(1e5);
+        u64_t f2 = (f0 & mask32) * 100;
+        COPY(b + 2, digits_dd[f2 >> 32]);
+
+        u64_t f4 = (f2 & mask32) * 100;
+        COPY(b + 4, digits_dd[f4 >> 32]);
+        return b + 6;
+    }
+
+    if (n < u64(1ull << 32ull)) {
+        if (n < u32(1e8)) {
+            u64_t f0 = u64(10 * (1ull << 48ull) / 1e7 + 1) * n >> 16;
+            COPY(b, digits_fd[f0 >> 32]);
+
+            b -= n < u32(1e7);
+            u64_t f2 = (f0 & mask32) * 100;
+            COPY(b + 2, digits_dd[f2 >> 32]);
+
+            u64_t f4 = (f2 & mask32) * 100;
+            COPY(b + 4, digits_dd[f4 >> 32]);
+
+            u64_t f6 = (f4 & mask32) * 100;
+            COPY(b + 6, digits_dd[f6 >> 32]);
+
+            return b + 8;
+        }
+
+        u64_t f0 = u64(10 * (1ull << 57ull) / 1e9 + 1) * n;
+        COPY(b, digits_fd[f0 >> 57]);
+
+        b -= n < u32(1e9);
+        u64_t f2 = (f0 & mask57) * 100;
+        COPY(b + 2, digits_dd[f2 >> 57]);
+
+        u64_t f4 = (f2 & mask57) * 100;
+        COPY(b + 4, digits_dd[f4 >> 57]);
+
+        u64_t f6 = (f4 & mask57) * 100;
+        COPY(b + 6, digits_dd[f6 >> 57]);
+
+        u64_t f8 = (f6 & mask57) * 100;
+        COPY(b + 8, digits_dd[f8 >> 57]);
+
+        return b + 10;
+    }
+
+    // if we get here U must be u64 but some compilers don't know that, so reassign n to a u64 to avoid warnings
+    u32_t z = n % u32(1e8);
+    u64_t u = n / u32(1e8);
+
+    if (u < u32(1e2)) {
+        // u can't be 1 digit (if u < 10 it would have been handled above as a 9 digit 32bit number)
+        COPY(b, digits_dd[u]);
+        b += 2;
+    }
+    else if (u < u32(1e6)) {
+        if (u < u32(1e4)) {
+            u32_t f0 = u32((10 * (1 << 24) / 1e3 + 1) * u);
+            COPY(b, digits_fd[f0 >> 24]);
+
+            b -= u < u32(1e3);
+            u32_t f2 = (f0 & mask24) * 100;
+            COPY(b + 2, digits_dd[f2 >> 24]);
+            b += 4;
+        }
+        else {
+            u64_t f0 = u64(10 * (1ull << 32ull) / 1e5 + 1) * u;
+            COPY(b, digits_fd[f0 >> 32]);
+
+            b -= u < u32(1e5);
+            u64_t f2 = (f0 & mask32) * 100;
+            COPY(b + 2, digits_dd[f2 >> 32]);
+
+            u64_t f4 = (f2 & mask32) * 100;
+            COPY(b + 4, digits_dd[f4 >> 32]);
+            b += 6;
+        }
+    }
+    else if (u < u32(1e8)) {
+        u64_t f0 = u64(10 * (1ull << 48ull) / 1e7 + 1) * u >> 16;
+        COPY(b, digits_fd[f0 >> 32]);
+
+        b -= u < u32(1e7);
+        u64_t f2 = (f0 & mask32) * 100;
+        COPY(b + 2, digits_dd[f2 >> 32]);
+
+        u64_t f4 = (f2 & mask32) * 100;
+        COPY(b + 4, digits_dd[f4 >> 32]);
+
+        u64_t f6 = (f4 & mask32) * 100;
+        COPY(b + 6, digits_dd[f6 >> 32]);
+
+        b += 8;
+    }
+    else if (u < u64(1ull << 32ull)) {
+        u64_t f0 = u64(10 * (1ull << 57ull) / 1e9 + 1) * u;
+        COPY(b, digits_fd[f0 >> 57]);
+
+        b -= u < u32(1e9);
+        u64_t f2 = (f0 & mask57) * 100;
+        COPY(b + 2, digits_dd[f2 >> 57]);
+
+        u64_t f4 = (f2 & mask57) * 100;
+        COPY(b + 4, digits_dd[f4 >> 57]);
+
+        u64_t f6 = (f4 & mask57) * 100;
+        COPY(b + 6, digits_dd[f6 >> 57]);
+
+        u64_t f8 = (f6 & mask57) * 100;
+        COPY(b + 8, digits_dd[f8 >> 57]);
+        b += 10;
+    }
+    else {
+        u32_t y = u % u32(1e8);
+        u /= u32(1e8);
+
+        // u is 2, 3, or 4 digits (if u < 10 it would have been handled above)
+        if (u < u32(1e2)) {
+            COPY(b, digits_dd[u]);
+            b += 2;
+        }
+        else {
+            u32_t f0 = u32((10 * (1 << 24) / 1e3 + 1) * u);
+            COPY(b, digits_fd[f0 >> 24]);
+
+            b -= u < u32(1e3);
+            u32_t f2 = (f0 & mask24) * 100;
+            COPY(b + 2, digits_dd[f2 >> 24]);
+
+            b += 4;
+        }
+        // do 8 digits
+        u64_t f0 = (u64((1ull << 48ull) / 1e6 + 1) * y >> 16) + 1;
+        COPY(b, digits_dd[f0 >> 32]);
+
+        u64_t f2 = (f0 & mask32) * 100;
+        COPY(b + 2, digits_dd[f2 >> 32]);
+
+        u64_t f4 = (f2 & mask32) * 100;
+        COPY(b + 4, digits_dd[f4 >> 32]);
+
+        u64_t f6 = (f4 & mask32) * 100;
+        COPY(b + 6, digits_dd[f6 >> 32]);
+        b += 8;
+    }
+
+    // do 8 digits
+    u64_t f0 = (u64((1ull << 48ull) / 1e6 + 1) * z >> 16) + 1;
+    COPY(b, digits_dd[f0 >> 32]);
+
+    u64_t f2 = (f0 & mask32) * 100;
+    COPY(b + 2, digits_dd[f2 >> 32]);
+
+    u64_t f4 = (f2 & mask32) * 100;
+    COPY(b + 4, digits_dd[f4 >> 32]);
+
+    u64_t f6 = (f4 & mask32) * 100;
+    COPY(b + 6, digits_dd[f6 >> 32]);
+
+    return b + 8;
+}
+
+#undef u32
+#undef u64
+#undef COPY
+
+#endif // JEAIII_TO_TEXT_H_

data/json.gemspec

@@ -1,67 +1,63 @@
-# -*- encoding: utf-8 -*-
+# frozen_string_literal: true
+
+version = File.foreach(File.join(__dir__, "lib/json/version.rb")) do |line|
+  /^\s*VERSION\s*=\s*'(.*)'/ =~ line and break $1
+end rescue nil
+
+spec = Gem::Specification.new do |s|
+  java_ext = Gem::Platform === s.platform && s.platform =~ 'java' || RUBY_ENGINE == 'jruby'
 
-Gem::Specification.new do |s|
   s.name = "json"
-  s.version = File.read(File.expand_path('../VERSION', __FILE__)).chomp
+  s.version = version
 
   s.summary = "JSON Implementation for Ruby"
-  s.description = "This is a JSON implementation as a Ruby extension in C."
+  s.homepage = "https://github.com/ruby/json"
+  s.metadata = {
+    'bug_tracker_uri'   => 'https://github.com/ruby/json/issues',
+    'changelog_uri'     => 'https://github.com/ruby/json/blob/master/CHANGES.md',
+    'documentation_uri' => 'https://docs.ruby-lang.org/en/master/JSON.html',
+    'homepage_uri'      => s.homepage,
+    'source_code_uri'   => 'https://github.com/ruby/json',
+  }
+
+  s.required_ruby_version = Gem::Requirement.new(">= 2.7")
+
+  if java_ext
+    s.description = "A JSON implementation as a JRuby extension."
+    s.author = "Daniel Luz"
+    s.email = "dev+ruby@mernen.com"
+  else
+    s.description = "This is a JSON implementation as a Ruby extension in C."
+    s.authors = ["Florian Frank"]
+    s.email = "flori@ping.de"
+  end
+
   s.licenses = ["Ruby"]
-  s.authors = ["Florian Frank"]
-  s.email = "flori@ping.de"
 
-  s.extensions = ["ext/json/ext/generator/extconf.rb", "ext/json/ext/parser/extconf.rb", "ext/json/extconf.rb"]
   s.extra_rdoc_files = ["README.md"]
   s.rdoc_options = ["--title", "JSON implementation for Ruby", "--main", "README.md"]
+
   s.files = [
     "CHANGES.md",
-    "LICENSE",
+    "COPYING",
+    "BSDL",
+    "LEGAL",
     "README.md",
-    "VERSION",
-    "ext/json/ext/fbuffer/fbuffer.h",
-    "ext/json/ext/generator/depend",
-    "ext/json/ext/generator/extconf.rb",
-    "ext/json/ext/generator/generator.c",
-    "ext/json/ext/generator/generator.h",
-    "ext/json/ext/parser/depend",
-    "ext/json/ext/parser/extconf.rb",
-    "ext/json/ext/parser/parser.c",
-    "ext/json/ext/parser/parser.h",
-    "ext/json/ext/parser/parser.rl",
-    "ext/json/extconf.rb",
     "json.gemspec",
-    "lib/json.rb",
-    "lib/json/add/bigdecimal.rb",
-    "lib/json/add/complex.rb",
-    "lib/json/add/core.rb",
-    "lib/json/add/date.rb",
-    "lib/json/add/date_time.rb",
-    "lib/json/add/exception.rb",
-    "lib/json/add/ostruct.rb",
-    "lib/json/add/range.rb",
-    "lib/json/add/rational.rb",
-    "lib/json/add/regexp.rb",
-    "lib/json/add/set.rb",
-    "lib/json/add/struct.rb",
-    "lib/json/add/symbol.rb",
-    "lib/json/add/time.rb",
-    "lib/json/common.rb",
-    "lib/json/ext.rb",
-    "lib/json/generic_object.rb",
-    "lib/json/pure.rb",
-    "lib/json/pure/generator.rb",
-    "lib/json/pure/parser.rb",
-    "lib/json/version.rb",
+    *Dir["lib/**/*.rb"],
   ]
-  s.homepage = "http://flori.github.com/json"
-  s.metadata = {
-    'bug_tracker_uri'   => 'https://github.com/flori/json/issues',
-    'changelog_uri'     => 'https://github.com/flori/json/blob/master/CHANGES.md',
-    'documentation_uri' => 'http://flori.github.io/json/doc/index.html',
-    'homepage_uri'      => 'http://flori.github.io/json/',
-    'source_code_uri'   => 'https://github.com/flori/json',
-    'wiki_uri'          => 'https://github.com/flori/json/wiki'
-  }
 
-  s.required_ruby_version = Gem::Requirement.new(">= 2.3")
+  if java_ext
+    s.platform = 'java'
+    s.files += Dir["lib/json/ext/**/*.jar"]
+  else
+    s.extensions = Dir["ext/json/**/extconf.rb"]
+    s.files += Dir["ext/json/**/*.{c,h}"]
+  end
+end
+
+if RUBY_ENGINE == 'jruby' && $0 == __FILE__
+  Gem::Builder.new(spec).build
+else
+  spec
 end

data/lib/json/add/bigdecimal.rb

@@ -1,29 +1,58 @@
-#frozen_string_literal: false
+# frozen_string_literal: true
 unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
   require 'json'
 end
-defined?(::BigDecimal) or require 'bigdecimal'
+begin
+  require 'bigdecimal'
+rescue LoadError
+end
 
 class BigDecimal
-  # Import a JSON Marshalled object.
-  #
-  # method used for JSON marshalling support.
+
+  # See #as_json.
   def self.json_create(object)
     BigDecimal._load object['b']
   end
 
-  # Marshal the object to JSON.
+  # Methods <tt>BigDecimal#as_json</tt> and +BigDecimal.json_create+ may be used
+  # to serialize and deserialize a \BigDecimal object;
+  # see Marshal[https://docs.ruby-lang.org/en/master/Marshal.html].
+  #
+  # \Method <tt>BigDecimal#as_json</tt> 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:
+  #
+  #   BigDecimal.json_create(x) # => 0.2e1
+  #   BigDecimal.json_create(y) # => 0.2e1
+  #   BigDecimal.json_create(z) # => 0.2e1
   #
-  # method used for JSON marshalling support.
   def as_json(*)
     {
       JSON.create_id => self.class.name,
-      'b'            => _dump,
+      'b'            => _dump.force_encoding(Encoding::UTF_8),
     }
   end
 
-  # 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(*args)
     as_json.to_json(*args)
   end
-end
+end if defined?(::BigDecimal)

data/lib/json/add/complex.rb

@@ -1,18 +1,31 @@
-#frozen_string_literal: false
+# frozen_string_literal: true
 unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
   require 'json'
 end
 
 class Complex
 
-  # Deserializes JSON string by converting Real value <tt>r</tt>, imaginary
-  # value <tt>i</tt>, to a Complex object.
+  # See #as_json.
   def self.json_create(object)
     Complex(object['r'], object['i'])
   end
 
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods <tt>Complex#as_json</tt> and +Complex.json_create+ may be used
+  # to serialize and deserialize a \Complex object;
+  # see Marshal[https://docs.ruby-lang.org/en/master/Marshal.html].
+  #
+  # \Method <tt>Complex#as_json</tt> 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(*)
     {
       JSON.create_id => self.class.name,
@@ -21,7 +34,17 @@ class Complex
     }
   end
 
-  # Stores class name (Complex) along with real value <tt>r</tt> and imaginary value <tt>i</tt> 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(*args)
     as_json.to_json(*args)
   end

data/lib/json/add/core.rb

@@ -1,4 +1,4 @@
-#frozen_string_literal: false
+# frozen_string_literal: true
 # This file requires the implementations of ruby core's custom objects for
 # serialisation/deserialisation.
 

data/lib/json/add/date.rb

@@ -1,4 +1,4 @@
-#frozen_string_literal: false
+# frozen_string_literal: true
 unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
   require 'json'
 end
@@ -6,16 +6,29 @@ require 'date'
 
 class Date
 
-  # Deserializes JSON string by converting Julian year <tt>y</tt>, month
-  # <tt>m</tt>, day <tt>d</tt> and Day of Calendar Reform <tt>sg</tt> to Date.
+  # See #as_json.
   def self.json_create(object)
     civil(*object.values_at('y', 'm', 'd', 'sg'))
   end
 
   alias start sg unless method_defined?(:start)
 
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods <tt>Date#as_json</tt> and +Date.json_create+ may be used
+  # to serialize and deserialize a \Date object;
+  # see Marshal[https://docs.ruby-lang.org/en/master/Marshal.html].
+  #
+  # \Method <tt>Date#as_json</tt> 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(*)
     {
       JSON.create_id => self.class.name,
@@ -26,8 +39,15 @@ class Date
     }
   end
 
-  # Stores class name (Date) with Julian year <tt>y</tt>, month <tt>m</tt>, day
-  # <tt>d</tt> and Day of Calendar Reform <tt>sg</tt> 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(*args)
     as_json.to_json(*args)
   end

data/lib/json/add/date_time.rb

@@ -1,4 +1,4 @@
-#frozen_string_literal: false
+# frozen_string_literal: true
 unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
   require 'json'
 end
@@ -6,9 +6,7 @@ require 'date'
 
 class DateTime
 
-  # Deserializes JSON string by converting year <tt>y</tt>, month <tt>m</tt>,
-  # day <tt>d</tt>, hour <tt>H</tt>, minute <tt>M</tt>, second <tt>S</tt>,
-  # offset <tt>of</tt> and Day of Calendar Reform <tt>sg</tt> to DateTime.
+  # See #as_json.
   def self.json_create(object)
     args = object.values_at('y', 'm', 'd', 'H', 'M', 'S')
     of_a, of_b = object['of'].split('/')
@@ -23,8 +21,21 @@ class DateTime
 
   alias start sg unless method_defined?(:start)
 
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods <tt>DateTime#as_json</tt> and +DateTime.json_create+ may be used
+  # to serialize and deserialize a \DateTime object;
+  # see Marshal[https://docs.ruby-lang.org/en/master/Marshal.html].
+  #
+  # \Method <tt>DateTime#as_json</tt> 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(*)
     {
       JSON.create_id => self.class.name,
@@ -39,9 +50,15 @@ class DateTime
     }
   end
 
-  # Stores class name (DateTime) with Julian year <tt>y</tt>, month <tt>m</tt>,
-  # day <tt>d</tt>, hour <tt>H</tt>, minute <tt>M</tt>, second <tt>S</tt>,
-  # offset <tt>of</tt> and Day of Calendar Reform <tt>sg</tt> 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(*args)
     as_json.to_json(*args)
   end