1 files changed, 27 insertions, 5 deletions
diff --git a/ext/json/lib/json/add/rational.rb b/ext/json/lib/json/add/rational.rb
index f776226046..8c39a7db55 100644
--- a/ext/json/lib/json/add/rational.rb
+++ b/ext/json/lib/json/add/rational.rb
@@ -4,14 +4,28 @@ unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
 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[rdoc-ref:Marshal].
+  #
+  # \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 @@ class Rational
     }
   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