More on additions RDoc

lib/json/add/complex.rb

@@ -24,7 +24,7 @@ def self.json_create(object)
   # \Method +JSON.create+ deserializes such a hash, returning a \Complex object:
   #
   #   Complex.json_create(x) # => (2+0i)
-  # Complex.json_create(y)   # => (2.0+4i)
+  #   Complex.json_create(y)   # => (2.0+4i)
   #
   def as_json(*)
     {

lib/json/add/exception.rb

@@ -5,16 +5,27 @@
 
 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 @@ def as_json(*)
     }
   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

lib/json/add/ostruct.rb

@@ -6,14 +6,27 @@
 
 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,8 +36,15 @@ def as_json(*)
     }
   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

lib/json/add/rational.rb

@@ -4,14 +4,28 @@
 end
 
 class Rational
-  # Deserializes JSON string by converting numerator value <tt>n</tt>,
-  # denominator value <tt>d</tt>, to a Rational object.
+
+  # See #as_json.
   def self.json_create(object)
     Rational(object['n'], object['d'])
   end
 
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods <tt>Rational#as_json</tt> and +Rational.json_create+ may be used
+  # to serialize and deserialize a \Rational object;
+  # see Marshal[https://docs.ruby-lang.org/en/master/Marshal.html].
+  #
+  # \Method <tt>Rational#as_json</tt> 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(*)
     {
       JSON.create_id => self.class.name,
@@ -20,7 +34,15 @@ def as_json(*)
     }
   end
 
-  # Stores class name (Rational) along with numerator value <tt>n</tt> and denominator value <tt>d</tt> 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(*args)
     as_json.to_json(*args)
   end

lib/json/add/regexp.rb

@@ -5,15 +5,26 @@
 
 class Regexp
 
-  # Deserializes JSON string by constructing new Regexp object with source
-  # <tt>s</tt> (Regexp or String) and options <tt>o</tt> serialized by
-  # <tt>to_json</tt>
+  # See #as_json.
   def self.json_create(object)
     new(object['s'], object['o'])
   end
 
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods <tt>Regexp#as_json</tt> and +Regexp.json_create+ may be used
+  # to serialize and deserialize a \Regexp object;
+  # see Marshal[https://docs.ruby-lang.org/en/master/Marshal.html].
+  #
+  # \Method <tt>Regexp#as_json</tt> 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(*)
     {
       JSON.create_id => self.class.name,
@@ -22,8 +33,15 @@ def as_json(*)
     }
   end
 
-  # Stores class name (Regexp) with options <tt>o</tt> and source <tt>s</tt>
-  # (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(*args)
     as_json.to_json(*args)
   end

lib/json/add/set.rb

@@ -4,24 +4,43 @@
 defined?(::Set) or require 'set'
 
 class Set
-  # Import a JSON Marshalled object.
-  #
-  # method used for JSON marshalling support.
+
+  # See #as_json.
   def self.json_create(object)
     new object['a']
   end
 
-  # Marshal the object to JSON.
+  # Methods <tt>Set#as_json</tt> and +Set.json_create+ may be used
+  # to serialize and deserialize a \Set object;
+  # see Marshal[https://docs.ruby-lang.org/en/master/Marshal.html].
+  #
+  # \Method <tt>Set#as_json</tt> 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:
+  #
+  #   Set.json_create(x) # => #<Set: {"foo", "bar", "baz"}>
   #
-  # method used for JSON marshalling support.
   def as_json(*)
     {
       JSON.create_id => self.class.name,
       'a'            => to_a,
     }
   end
 
-  # 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(*args)
     as_json.to_json(*args)
   end

lib/json/add/struct.rb

@@ -5,14 +5,28 @@
 
 class Struct
 
-  # Deserializes JSON string by constructing new Struct object with values
-  # <tt>v</tt> serialized by <tt>to_json</tt>.
+  # See #as_json.
   def self.json_create(object)
     new(*object['v'])
   end
 
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods <tt>Struct#as_json</tt> and +Struct.json_create+ may be used
+  # to serialize and deserialize a \Struct object;
+  # see Marshal[https://docs.ruby-lang.org/en/master/Marshal.html].
+  #
+  # \Method <tt>Struct#as_json</tt> 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(*)
     klass = self.class.name
     klass.to_s.empty? and raise JSON::JSONError, "Only named structs are supported!"
@@ -22,8 +36,16 @@ def as_json(*)
     }
   end
 
-  # Stores class name (Struct) with Struct values <tt>v</tt> 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(*args)
     as_json.to_json(*args)
   end