Improve generation options documentation

Author: byroot

.gitignore

@@ -21,4 +21,4 @@ Gemfile.lock
 .byebug_history
 *.log
 /tmp
-
+/doc/

lib/json.rb

@@ -307,6 +307,25 @@
 #
 # ---
 #
+# Option +allow_duplicate_key+ (boolean) specifies whether
+# hashes with duplicate keys should be allowed or produce an error.
+# defaults to emit a deprecation warning.
+#
+# With the default, (not set):
+#   Warning[:deprecated] = true
+#   JSON.generate({ foo: 1, "foo" => 2 })
+#   # warning: detected duplicate key "foo" in {foo: 1, "foo" => 2}.
+#   # This will raise an error in json 3.0 unless enabled via `allow_duplicate_key: true`
+#   # => '{"foo":1,"foo":2}'
+#
+# With <tt>false</tt>
+#   JSON.generate({ foo: 1, "foo" => 2 }, allow_duplicate_key: false)
+#   # detected duplicate key "foo" in {foo: 1, "foo" => 2} (JSON::GeneratorError)
+#
+# In version 3.0, <tt>false</tt> will become the default.
+#
+# ---
+#
 # Option +max_nesting+ (\Integer) specifies the maximum nesting depth
 # in +obj+; defaults to +100+.
 #
@@ -384,6 +403,9 @@
 #
 # == \JSON Additions
 #
+# Note that JSON Additions must only be used with trusted data, and is
+# deprecated.
+#
 # When you "round trip" a non-\String object from Ruby to \JSON and back,
 # you have a new \String, instead of the object you began with:
 #   ruby0 = Range.new(0, 2)

lib/json/ext/generator/state.rb

@@ -8,20 +8,8 @@ class State
         #
         # Instantiates a new State object, configured by _opts_.
         #
-        # _opts_ can have the following keys:
-        #
-        # * *indent*: a string used to indent levels (default: ''),
-        # * *space*: a string that is put after, a : or , delimiter (default: ''),
-        # * *space_before*: a string that is put before a : pair delimiter (default: ''),
-        # * *object_nl*: a string that is put at the end of a JSON object (default: ''),
-        # * *array_nl*: a string that is put at the end of a JSON array (default: ''),
-        # * *allow_nan*: true if NaN, Infinity, and -Infinity should be
-        #   generated, otherwise an exception is thrown, if these values are
-        #   encountered. This options defaults to false.
-        # * *ascii_only*: true if only ASCII characters should be generated. This
-        #   option defaults to false.
-        # * *buffer_initial_length*: sets the initial length of the generator's
-        #   internal buffer.
+        # Argument +opts+, if given, contains a \Hash of options for the generation.
+        # See {Generating Options}[#module-JSON-label-Generating+Options].
         def initialize(opts = nil)
           if opts && !opts.empty?
             configure(opts)