1 files changed, 28 insertions, 5 deletions
diff --git a/ext/json/lib/json/add/complex.rb b/ext/json/lib/json/add/complex.rb
index e63e29fd22..ef48c554c6 100644
--- a/ext/json/lib/json/add/complex.rb
+++ b/ext/json/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[rdoc-ref:Marshal].
+  #
+  # \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