json filter docs

lib/logstash/filters/json.rb

@@ -2,18 +2,22 @@
 require "logstash/filters/base"
 require "logstash/namespace"
 
-# JSON filter. Takes a field that contains JSON and expands it into
-# an actual datastructure.
+# This is a JSON parsing filter. It takes an existing field which contains JSON and
+# expands it into an actual datastructure within the logstash event.
+# 
+# By default it will place the parsed JSON in the root of the logstash event, but this
+# filter can be configured to place the JSON into any arbitrary event field, using the
+# `target` configuration.
 class LogStash::Filters::Json < LogStash::Filters::Base
 
   config_name "json"
   milestone 2
 
-  # Config for json is:
+  # The configuration for the JSON filter:
   #
   #     source => source_field
   #
-  # For example, if you have json data in the @message field:
+  # For example, if you have JSON data in the @message field:
   #
   #     filter {
   #       json {
@@ -24,21 +28,21 @@ class LogStash::Filters::Json < LogStash::Filters::Base
   # The above would parse the json from the @message field
   config :source, :validate => :string, :required => true
 
-  # Define target for placing the data. If this setting is omitted,
-  # the json data will be stored at the root of the event.
+  # Define the target field for placing the parsed data. If this setting is
+  # ommitted, the JSON data will be stored at the root of the event.
   #
-  # For example if you want the data to be put in the 'doc' field:
+  # For example, if you want the data to be put in the 'doc' field:
   #
   #     filter {
   #       json {
   #         target => "doc"
   #       }
   #     }
   #
-  # json in the value of the source field will be expanded into a
-  # datastructure in the "target" field.
+  # JSON in the value of the `source` field will be expanded into a
+  # datastructure in the `target` field.
   #
-  # Note: if the "target" field already exists, it will be overwritten.
+  # NOTE: if the `target` field already exists, it will be overwritten!
   config :target, :validate => :string
 
   public