From c11bcb409456984d2d28ffe7a0e020eee39800ca Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Fri, 24 Nov 2023 17:07:45 -0600 Subject: [PATCH] More on additions RDoc --- lib/json/add/complex.rb | 2 +- lib/json/add/exception.rb | 30 ++++++++++++++++++++++++------ lib/json/add/ostruct.rb | 32 ++++++++++++++++++++++++++------ lib/json/add/rational.rb | 32 +++++++++++++++++++++++++++----- lib/json/add/regexp.rb | 32 +++++++++++++++++++++++++------- lib/json/add/set.rb | 31 +++++++++++++++++++++++++------ lib/json/add/struct.rb | 34 ++++++++++++++++++++++++++++------ 7 files changed, 156 insertions(+), 37 deletions(-) diff --git a/lib/json/add/complex.rb b/lib/json/add/complex.rb index c75d0cc0b..4af022dbb 100644 --- a/lib/json/add/complex.rb +++ b/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(*) { diff --git a/lib/json/add/exception.rb b/lib/json/add/exception.rb index a107e5b3c..fa699d6e3 100644 --- a/lib/json/add/exception.rb +++ b/lib/json/add/exception.rb @@ -5,16 +5,27 @@ class Exception - # Deserializes JSON string by constructing new Exception object with message - # m and backtrace b serialized with to_json + # 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 Exception#as_json 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 Exception#as_json 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) # => # + # def as_json(*) { JSON.create_id => self.class.name, @@ -23,8 +34,15 @@ def as_json(*) } end - # Stores class name (Exception) with message m and backtrace array - # b 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 diff --git a/lib/json/add/ostruct.rb b/lib/json/add/ostruct.rb index 686cf0025..f912e5226 100644 --- a/lib/json/add/ostruct.rb +++ b/lib/json/add/ostruct.rb @@ -6,14 +6,27 @@ class OpenStruct - # Deserializes JSON string by constructing new Struct object with values - # t serialized by to_json. + # 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 OpenStruct#as_json 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 OpenStruct#as_json 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) + # # => # + # 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 t 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 diff --git a/lib/json/add/rational.rb b/lib/json/add/rational.rb index f77622604..a6033774b 100644 --- a/lib/json/add/rational.rb +++ b/lib/json/add/rational.rb @@ -4,14 +4,28 @@ end class Rational - # Deserializes JSON string by converting numerator value n, - # denominator value d, 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 Rational#as_json 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 Rational#as_json 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 n and denominator value d 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 diff --git a/lib/json/add/regexp.rb b/lib/json/add/regexp.rb index 39d69fede..5649a0726 100644 --- a/lib/json/add/regexp.rb +++ b/lib/json/add/regexp.rb @@ -5,15 +5,26 @@ class Regexp - # Deserializes JSON string by constructing new Regexp object with source - # s (Regexp or String) and options o serialized by - # to_json + # 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 Regexp#as_json 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 Regexp#as_json 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 o and source s - # (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 diff --git a/lib/json/add/set.rb b/lib/json/add/set.rb index 71e2a0ac8..c521d8b90 100644 --- a/lib/json/add/set.rb +++ b/lib/json/add/set.rb @@ -4,16 +4,27 @@ 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 Set#as_json 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 Set#as_json 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) # => # # - # method used for JSON marshalling support. def as_json(*) { JSON.create_id => self.class.name, @@ -21,7 +32,15 @@ def as_json(*) } 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 diff --git a/lib/json/add/struct.rb b/lib/json/add/struct.rb index e8395ed42..857bc8fd7 100644 --- a/lib/json/add/struct.rb +++ b/lib/json/add/struct.rb @@ -5,14 +5,28 @@ class Struct - # Deserializes JSON string by constructing new Struct object with values - # v serialized by to_json. + # 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 Struct#as_json 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 Struct#as_json 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) + # # => # + # 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 v 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