Clarify documentation on how to define filters

lib/rackstash/filter.rb

@@ -43,8 +43,8 @@ module Rackstash
         filter_class
       end
 
-      # @return [ClassRegistry] the registry object which allows to register and
+      # @return [ClassRegistry] the {ClassRegistry} object which allows to
-      #   retrieve available filter classes
+      #   register and retrieve available filter classes
       def registry
         @registry ||= Rackstash::ClassRegistry.new('filter'.freeze)
       end
@@ -58,7 +58,7 @@ module Rackstash
       #   class from which we are creating a new filter object. When giving a
       #   `Class`, we are using it as is to create a new filter object with the
       #   supplied `args` and `block`. When giving a `String` or `Symbol`, we
-      #   first use the filter registry to find the matching class. With that,
+      #   first use the filter {.registry} to find the matching class. With that
       #   we then create a filter object as before. When giving an object which
       #   responds to `call` already (e.g. a `Proc`, we return it unchanged,
       #   ignoring any additional passed `args`.

lib/rackstash/filter_chain.rb

@@ -294,13 +294,13 @@ module Rackstash
     # Build a new filter instance from the given specification.
     #
     # @param filter_spec [Array] the description of a filter to create. If you
-    #   give a single `Proc` or a block (or another object which responds to
+    #   give a single `Proc` (or any other object which responds to `#call`) or
-    #   `#call`), we will directly return it. If you give a `Class` plus any
+    #   simply a proc, we will directly return it. If you give a `Class` plus
-    #   optional initializer arguments, we will return a new instance of that
+    #   any optional initializer arguments, we will return a new instance of
-    #   class. When giving a `String` or `Symbol`, we will resolve it to a
+    #   that class. When giving a `String` or `Symbol`, we first use the
-    #   filter class from the {Rackstash::Filter} module and create a new
+    #   {Filter.registry} to find the matching filter class. With that class,
-    #   instance of that class with the additional arguments given to
+    #   we then create a filter object as before using the additional arguments
-    #   `initialize`.
+    #   given to `initialize`.
     # @return [#call] a filter instance
     def build_filter(filter_spec, &block)
       if filter_spec.empty?