[DOC] RDoc for additions (#557)

* RDoc for additions

* Update lib/json/add/time.rb

Co-authored-by: Hiroshi SHIBATA <hsbt@ruby-lang.org>

---------

Co-authored-by: Hiroshi SHIBATA <hsbt@ruby-lang.org>

lib/json/add/bigdecimal.rb

@@ -8,24 +8,50 @@
 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,
     }
   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

lib/json/add/complex.rb

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

lib/json/add/date.rb

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

lib/json/add/date_time.rb

@@ -6,9 +6,7 @@
 
 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 @@ def self.json_create(object)
 
   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 @@ def as_json(*)
     }
   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

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/range.rb

@@ -5,24 +5,28 @@
 
 class Range
 
-  # Returns a new \Range object constructed from <tt>object['a']</tt>,
-  # which must be an array of values suitable for a call to Range.new:
-  #
-  #   require 'json/add/range'
-  #   Range.json_create({"a"=>[1, 4]})        # => 1..4
-  #   Range.json_create({"a"=>[1, 4, true]}) # => 1...4
-  #   Range.json_create({"a" => ['a', 'd']})  # => "a".."d"
-  #
+  # See #as_json.
   def self.json_create(object)
     new(*object['a'])
   end
 
-  # Returns a 2-element hash representing +self+:
+  # Methods <tt>Range#as_json</tt> and +Range.json_create+ may be used
+  # to serialize and deserialize a \Range object;
+  # see Marshal[https://docs.ruby-lang.org/en/master/Marshal.html].
+  #
+  # \Method <tt>Range#as_json</tt> serializes +self+,
+  # returning a 2-element hash representing +self+:
   #
   #   require 'json/add/range'
-  #   (1..4).as_json     # => {"json_class"=>"Range", "a"=>[1, 4, false]}
-  #   (1...4).as_json    # => {"json_class"=>"Range", "a"=>[1, 4, true]}
-  #   ('a'..'d').as_json # => {"json_class"=>"Range", "a"=>["a", "d", false]}
+  #   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(*)
     {
@@ -34,9 +38,15 @@ def as_json(*)
   # Returns a JSON string representing +self+:
   #
   #   require 'json/add/range'
-  #   (1..4).to_json   # => "{\"json_class\":\"Range\",\"a\":[1,4,false]}"
-  #   (1...4).to_json    # => "{\"json_class\":\"Range\",\"a\":[1,4,true]}"
-  #   ('a'..'d').to_json # => "{\"json_class\":\"Range\",\"a\":[\"a\",\"d\",false]}"
+  #   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(*args)
     as_json.to_json(*args)