json 2.6.2 → 2.7.2

data/ext/json/ext/parser/parser.rl

@@ -222,14 +222,14 @@ static char *JSON_parse_object(JSON_Parser *json, char *p, char *pe, VALUE *resu
         if (json->allow_nan) {
             *result = CNaN;
         } else {
-            rb_enc_raise(EXC_ENCODING eParserError, "%u: unexpected token at '%s'", __LINE__, p - 2);
+            rb_enc_raise(EXC_ENCODING eParserError, "unexpected token at '%s'", p - 2);
         }
     }
     action parse_infinity {
         if (json->allow_nan) {
             *result = CInfinity;
         } else {
-            rb_enc_raise(EXC_ENCODING eParserError, "%u: unexpected token at '%s'", __LINE__, p - 8);
+            rb_enc_raise(EXC_ENCODING eParserError, "unexpected token at '%s'", p - 7);
         }
     }
     action parse_string {
@@ -245,7 +245,7 @@ static char *JSON_parse_object(JSON_Parser *json, char *p, char *pe, VALUE *resu
                 fexec p + 10;
                 fhold; fbreak;
             } else {
-                rb_enc_raise(EXC_ENCODING eParserError, "%u: unexpected token at '%s'", __LINE__, p);
+                rb_enc_raise(EXC_ENCODING eParserError, "unexpected token at '%s'", p);
             }
         }
         np = JSON_parse_float(json, fpc, pe, result);
@@ -447,7 +447,7 @@ static char *JSON_parse_array(JSON_Parser *json, char *p, char *pe, VALUE *resul
     if(cs >= JSON_array_first_final) {
         return p + 1;
     } else {
-        rb_enc_raise(EXC_ENCODING eParserError, "%u: unexpected token at '%s'", __LINE__, p);
+        rb_enc_raise(EXC_ENCODING eParserError, "unexpected token at '%s'", p);
         return NULL;
     }
 }
@@ -508,11 +508,11 @@ static VALUE json_string_unescape(char *string, char *stringEnd, int intern, int
                 case 'u':
                     if (pe > stringEnd - 4) {
                       if (bufferSize > MAX_STACK_BUFFER_SIZE) {
-                        free(bufferStart);
+                        ruby_xfree(bufferStart);
                       }
                       rb_enc_raise(
                         EXC_ENCODING eParserError,
-                        "%u: incomplete unicode character escape sequence at '%s'", __LINE__, p
+                        "incomplete unicode character escape sequence at '%s'", p
                       );
                     } else {
                         UTF32 ch = unescape_unicode((unsigned char *) ++pe);
@@ -521,11 +521,11 @@ static VALUE json_string_unescape(char *string, char *stringEnd, int intern, int
                             pe++;
                             if (pe > stringEnd - 6) {
                               if (bufferSize > MAX_STACK_BUFFER_SIZE) {
-                                free(bufferStart);
+                                ruby_xfree(bufferStart);
                               }
                               rb_enc_raise(
                                 EXC_ENCODING eParserError,
-                                "%u: incomplete surrogate pair at '%s'", __LINE__, p
+                                "incomplete surrogate pair at '%s'", p
                                 );
                             }
                             if (pe[0] == '\\' && pe[1] == 'u') {
@@ -566,13 +566,13 @@ static VALUE json_string_unescape(char *string, char *stringEnd, int intern, int
         result = rb_utf8_str_new(bufferStart, (long)(buffer - bufferStart));
       }
       if (bufferSize > MAX_STACK_BUFFER_SIZE) {
-        free(bufferStart);
+        ruby_xfree(bufferStart);
       }
 # else
       result = rb_utf8_str_new(bufferStart, (long)(buffer - bufferStart));
 
       if (bufferSize > MAX_STACK_BUFFER_SIZE) {
-        free(bufferStart);
+        ruby_xfree(bufferStart);
       }
 
       if (intern) {
@@ -691,8 +691,6 @@ static VALUE convert_encoding(VALUE source)
  *
  * Creates a new JSON::Ext::Parser instance for the string _source_.
  *
- * Creates a new JSON::Ext::Parser instance for the string _source_.
- *
  * It will be configured by the _opts_ hash. _opts_ can have the following
  * keys:
  *
@@ -721,98 +719,85 @@ static VALUE cParser_initialize(int argc, VALUE *argv, VALUE self)
     if (json->Vsource) {
         rb_raise(rb_eTypeError, "already initialized instance");
     }
-#ifdef HAVE_RB_SCAN_ARGS_OPTIONAL_HASH
     rb_scan_args(argc, argv, "1:", &source, &opts);
-#else
-    rb_scan_args(argc, argv, "11", &source, &opts);
-#endif
     if (!NIL_P(opts)) {
-#ifndef HAVE_RB_SCAN_ARGS_OPTIONAL_HASH
-        opts = rb_convert_type(opts, T_HASH, "Hash", "to_hash");
-        if (NIL_P(opts)) {
-            rb_raise(rb_eArgError, "opts needs to be like a hash");
-        } else {
-#endif
-            VALUE tmp = ID2SYM(i_max_nesting);
-            if (option_given_p(opts, tmp)) {
-                VALUE max_nesting = rb_hash_aref(opts, tmp);
-                if (RTEST(max_nesting)) {
-                    Check_Type(max_nesting, T_FIXNUM);
-                    json->max_nesting = FIX2INT(max_nesting);
-                } else {
-                    json->max_nesting = 0;
-                }
-            } else {
-                json->max_nesting = 100;
-            }
-            tmp = ID2SYM(i_allow_nan);
-            if (option_given_p(opts, tmp)) {
-                json->allow_nan = RTEST(rb_hash_aref(opts, tmp)) ? 1 : 0;
-            } else {
-                json->allow_nan = 0;
-            }
-            tmp = ID2SYM(i_symbolize_names);
-            if (option_given_p(opts, tmp)) {
-                json->symbolize_names = RTEST(rb_hash_aref(opts, tmp)) ? 1 : 0;
-            } else {
-                json->symbolize_names = 0;
-            }
-            tmp = ID2SYM(i_freeze);
-            if (option_given_p(opts, tmp)) {
-                json->freeze = RTEST(rb_hash_aref(opts, tmp)) ? 1 : 0;
-            } else {
-                json->freeze = 0;
-            }
-            tmp = ID2SYM(i_create_additions);
-            if (option_given_p(opts, tmp)) {
-                json->create_additions = RTEST(rb_hash_aref(opts, tmp));
-            } else {
-                json->create_additions = 0;
-            }
-            if (json->symbolize_names && json->create_additions) {
-              rb_raise(rb_eArgError,
-                "options :symbolize_names and :create_additions cannot be "
-                " used in conjunction");
-            }
-            tmp = ID2SYM(i_create_id);
-            if (option_given_p(opts, tmp)) {
-                json->create_id = rb_hash_aref(opts, tmp);
-            } else {
-                json->create_id = rb_funcall(mJSON, i_create_id, 0);
-            }
-            tmp = ID2SYM(i_object_class);
-            if (option_given_p(opts, tmp)) {
-                json->object_class = rb_hash_aref(opts, tmp);
-            } else {
-                json->object_class = Qnil;
-            }
-            tmp = ID2SYM(i_array_class);
-            if (option_given_p(opts, tmp)) {
-                json->array_class = rb_hash_aref(opts, tmp);
-            } else {
-                json->array_class = Qnil;
-            }
-            tmp = ID2SYM(i_decimal_class);
-            if (option_given_p(opts, tmp)) {
-                json->decimal_class = rb_hash_aref(opts, tmp);
-            } else {
-                json->decimal_class = Qnil;
-            }
-            tmp = ID2SYM(i_match_string);
-            if (option_given_p(opts, tmp)) {
-                VALUE match_string = rb_hash_aref(opts, tmp);
-                json->match_string = RTEST(match_string) ? match_string : Qnil;
-            } else {
-                json->match_string = Qnil;
-            }
-#ifndef HAVE_RB_SCAN_ARGS_OPTIONAL_HASH
-        }
-#endif
+	VALUE tmp = ID2SYM(i_max_nesting);
+	if (option_given_p(opts, tmp)) {
+	    VALUE max_nesting = rb_hash_aref(opts, tmp);
+	    if (RTEST(max_nesting)) {
+		Check_Type(max_nesting, T_FIXNUM);
+		json->max_nesting = FIX2INT(max_nesting);
+	    } else {
+		json->max_nesting = 0;
+	    }
+	} else {
+	    json->max_nesting = 100;
+	}
+	tmp = ID2SYM(i_allow_nan);
+	if (option_given_p(opts, tmp)) {
+	    json->allow_nan = RTEST(rb_hash_aref(opts, tmp)) ? 1 : 0;
+	} else {
+	    json->allow_nan = 0;
+	}
+	tmp = ID2SYM(i_symbolize_names);
+	if (option_given_p(opts, tmp)) {
+	    json->symbolize_names = RTEST(rb_hash_aref(opts, tmp)) ? 1 : 0;
+	} else {
+	    json->symbolize_names = 0;
+	}
+	tmp = ID2SYM(i_freeze);
+	if (option_given_p(opts, tmp)) {
+	    json->freeze = RTEST(rb_hash_aref(opts, tmp)) ? 1 : 0;
+	} else {
+	    json->freeze = 0;
+	}
+	tmp = ID2SYM(i_create_additions);
+	if (option_given_p(opts, tmp)) {
+	    json->create_additions = RTEST(rb_hash_aref(opts, tmp));
+	} else {
+	    json->create_additions = 0;
+	}
+	if (json->symbolize_names && json->create_additions) {
+	    rb_raise(rb_eArgError,
+		     "options :symbolize_names and :create_additions cannot be "
+		     " used in conjunction");
+	}
+	tmp = ID2SYM(i_create_id);
+	if (option_given_p(opts, tmp)) {
+	    json->create_id = rb_hash_aref(opts, tmp);
+	} else {
+	    json->create_id = rb_funcall(mJSON, i_create_id, 0);
+	}
+	tmp = ID2SYM(i_object_class);
+	if (option_given_p(opts, tmp)) {
+	    json->object_class = rb_hash_aref(opts, tmp);
+	} else {
+	    json->object_class = Qnil;
+	}
+	tmp = ID2SYM(i_array_class);
+	if (option_given_p(opts, tmp)) {
+	    json->array_class = rb_hash_aref(opts, tmp);
+	} else {
+	    json->array_class = Qnil;
+	}
+	tmp = ID2SYM(i_decimal_class);
+	if (option_given_p(opts, tmp)) {
+	    json->decimal_class = rb_hash_aref(opts, tmp);
+	} else {
+	    json->decimal_class = Qnil;
+	}
+	tmp = ID2SYM(i_match_string);
+	if (option_given_p(opts, tmp)) {
+	    VALUE match_string = rb_hash_aref(opts, tmp);
+	    json->match_string = RTEST(match_string) ? match_string : Qnil;
+	} else {
+	    json->match_string = Qnil;
+	}
     } else {
         json->max_nesting = 100;
         json->allow_nan = 0;
         json->create_additions = 0;
-        json->create_id = rb_funcall(mJSON, i_create_id, 0);
+        json->create_id = Qnil;
         json->object_class = Qnil;
         json->array_class = Qnil;
         json->decimal_class = Qnil;
@@ -847,7 +832,7 @@ static VALUE cParser_initialize(int argc, VALUE *argv, VALUE self)
  *
  *  Parses the current JSON text _source_ and returns the complete data
  *  structure as a result.
- *  It raises JSON::ParseError if fail to parse.
+ *  It raises JSON::ParserError if fail to parse.
  */
 static VALUE cParser_parse(VALUE self)
 {
@@ -864,7 +849,7 @@ static VALUE cParser_parse(VALUE self)
   if (cs >= JSON_first_final && p == pe) {
     return result;
   } else {
-    rb_enc_raise(EXC_ENCODING eParserError, "%u: unexpected token at '%s'", __LINE__, p);
+    rb_enc_raise(EXC_ENCODING eParserError, "unexpected token at '%s'", p);
     return Qnil;
   }
 }

data/json.gemspec

@@ -1,8 +1,10 @@
-# -*- encoding: utf-8 -*-
+version = File.foreach(File.join(__dir__, "lib/json/version.rb")) do |line|
+  /^\s*VERSION\s*=\s*'(.*)'/ =~ line and break $1
+end rescue nil
 
 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."
@@ -17,7 +19,6 @@ Gem::Specification.new do |s|
     "CHANGES.md",
     "LICENSE",
     "README.md",
-    "VERSION",
     "ext/json/ext/fbuffer/fbuffer.h",
     "ext/json/ext/generator/depend",
     "ext/json/ext/generator/extconf.rb",
@@ -53,12 +54,12 @@ Gem::Specification.new do |s|
     "lib/json/pure/parser.rb",
     "lib/json/version.rb",
   ]
-  s.homepage = "http://flori.github.com/json"
+  s.homepage = "https://flori.github.io/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/',
+    'documentation_uri' => 'https://flori.github.io/json/doc/index.html',
+    'homepage_uri'      => s.homepage,
     'source_code_uri'   => 'https://github.com/flori/json',
     'wiki_uri'          => 'https://github.com/flori/json/wiki'
   }

data/lib/json/add/bigdecimal.rb

@@ -2,19 +2,36 @@
 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,
@@ -22,8 +39,20 @@ class BigDecimal
     }
   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

@@ -5,14 +5,27 @@ 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/date.rb

@@ -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

@@ -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

data/lib/json/add/exception.rb

@@ -5,16 +5,27 @@ end
 
 class Exception
 
-  # Deserializes JSON string by constructing new Exception object with message
-  # <tt>m</tt> and backtrace <tt>b</tt> serialized with <tt>to_json</tt>
+  # See #as_json.
   def self.json_create(object)
     result = new(object['m'])
     result.set_backtrace object['b']
     result
   end
 
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods <tt>Exception#as_json</tt> and +Exception.json_create+ may be used
+  # to serialize and deserialize a \Exception object;
+  # see Marshal[https://docs.ruby-lang.org/en/master/Marshal.html].
+  #
+  # \Method <tt>Exception#as_json</tt> 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(*)
     {
       JSON.create_id => self.class.name,
@@ -23,8 +34,15 @@ class Exception
     }
   end
 
-  # Stores class name (Exception) with message <tt>m</tt> and backtrace array
-  # <tt>b</tt> 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(*args)
     as_json.to_json(*args)
   end

data/lib/json/add/ostruct.rb

@@ -2,18 +2,34 @@
 unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
   require 'json'
 end
-require 'ostruct'
+begin
+  require 'ostruct'
+rescue LoadError
+end
 
 class OpenStruct
 
-  # Deserializes JSON string by constructing new Struct object with values
-  # <tt>t</tt> serialized by <tt>to_json</tt>.
+  # See #as_json.
   def self.json_create(object)
     new(object['t'] || object[:t])
   end
 
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods <tt>OpenStruct#as_json</tt> and +OpenStruct.json_create+ may be used
+  # to serialize and deserialize a \OpenStruct object;
+  # see Marshal[https://docs.ruby-lang.org/en/master/Marshal.html].
+  #
+  # \Method <tt>OpenStruct#as_json</tt> 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(*)
     klass = self.class.name
     klass.to_s.empty? and raise JSON::JSONError, "Only named structs are supported!"
@@ -23,9 +39,16 @@ class OpenStruct
     }
   end
 
-  # Stores class name (OpenStruct) with this struct's values <tt>t</tt> 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(*args)
     as_json.to_json(*args)
   end
-end
+end if defined?(::OpenStruct)