Improve code documentation

lib/rackstash/buffer.rb

@@ -14,7 +14,7 @@ module Rackstash
   # is set on a Buffer. Each Buffer belongs to exactly one {BufferStack} (and
   # thus in turn to exactly one {Logger}) which creates it and controls its
   # complete life cycle. The data a buffer holds can be exported via a {Sink}
-  # and passed on to one or more {Target}s which send the data to an external
+  # and passed on to one or more {Flow}s which send the data to an external
   # log receiver.
   #
   # Most methods of the Buffer are directly exposed to the user-accessible
@@ -59,7 +59,7 @@ module Rackstash
     #   current buffer. It contains frozen strings only.
     attr_reader :tags
 
-    # @return [Sink] the log sink where the buffer is eventually flushed to
+    # @return [Sink] the log {Sink} where the buffer is eventually flushed to
     attr_reader :sink
 
     # @param buffering [Boolean] When set to `true`, this buffer is considered
@@ -136,8 +136,11 @@ module Rackstash
       self
     end
 
-    # Flush the current buffer to the log sink. Does nothing if the buffer is
+    # Flush the current buffer to the log {#sink} if it is pending.
-    # not pending.
+    #
+    # After the flush, the existing buffer should not be used anymore. You
+    # should either call {#clear} to remove all volatile data or create a new
+    # buffer instance instead.
     #
     # @return [self,nil] returns `self` if the buffer was flushed, `nil`
     #   otherwise
@@ -153,7 +156,7 @@ module Rackstash
     # @return [Array<Message>] the list of messages of the curent buffer
     # @note You can not add messsages to the buffer by modifying this array.
     #   Instead, use {#add_message} to add new messages or add filters to the
-    #   responsible codec to remove or change messages.
+    #   responsible {Flow} to remove or change messages.
     def messages
       @messages.dup
     end

lib/rackstash/fields/array.rb

@@ -66,7 +66,7 @@ module Rackstash
       #
       # You can set nested hashes and arrays here.
       #
-      # @param index [Integer] the index in the array where we fetch the value
+      # @param index [Integer] the index in the array where we set the value
       # @param value [Object, Proc] any value which can be serialized to JSON.
       #   The value will be normalized before being set so that only JSON-
       #   compatible objects are added into the array.

lib/rackstash/fields/hash.rb

@@ -258,7 +258,7 @@ module Rackstash
       #   the hash to merge into `self`. If this is a proc, it will get called
       #   and its result is used instead.
       # @param force [Boolean] `true` to raise an `ArgumentError` when trying to
-      #   set a forbidden key, `false` to silently ingnore these key-value pairs
+      #   set a forbidden key, `false` to silently ignore these key-value pairs
       # @param scope [Object, nil] if `hash` or any of its (deeply-nested)
       #   values is a proc, it will be called in the instance scope of this
       #   object (when given).
@@ -304,7 +304,7 @@ module Rackstash
       #   the hash to merge into `self`. If this is a proc, it will get called
       #   and its result is used instead
       # @param force [Boolean] `true` to raise an `ArgumentError` when trying to
-      #   set a forbidden key, `false` to silently ingnore these key-value pairs
+      #   set a forbidden key, `false` to silently ignore these key-value pairs
       # @param scope [Object, nil] if `hash` or any of its (deeply-nested)
       #   values is a proc, it will be called in the instance scope of this
       #   object (when given).

lib/rackstash/flows.rb

@@ -11,9 +11,10 @@ module Rackstash
   # The `Flows` class provides a thread-safe list of {Flow} objects which are
   # used to dispatch a single log events to multiple flows from the {Sink}.
   class Flows
-    # @param flows ::Array<Flow, Adapter> the {Flow} objects which should be
+    # @param flows [::Array<Flow, Adapters::Adapter, Object>] the {Flow} objects
-    #   part of the list. If any of the arguments is not a {Flow} already, we
+    #   which should be part of the list. If any of the arguments is not a
-    #   assume it is an adapter and create a new {Flow} for it.
+    #   {Flow} already, we assume it is an adapter and create a new {Flow} for
+    #   it.
     def initialize(*flows)
       @flows = Concurrent::Array.new
 
@@ -24,9 +25,9 @@ module Rackstash
 
     # Add a new flow at the end of the list.
     #
-    # @param flow [Flow, Adapter] The flow to add to the end of the list. If
+    # @param flow [Flow, Adapters::Adapter, Object] The flow to add to the end
-    #   the argument is not a {Flow}, we assume it is an adapter and create a
+    #   of the list. If the argument is not a {Flow}, we assume it is an adapter
-    #   new {Flow} for it.
+    #   and create a new {Flow} with it.
     # @return [self]
     def <<(flow)
       flow = Flow.new(flow) unless flow.is_a?(Flow)
@@ -47,9 +48,9 @@ module Rackstash
     # is an adapter and create a new {Flow} for it.
     #
     # @param index [Integer] the index in the list where we set the flow
-    # @param value [Flow, Adapter] The flow to add to the end at `index`. If the
+    # @param flow [Flow, Adapters::Adapter, Object] The flow to add at `index`.
-    #   argument is not a {Flow}, we assume it is an adapter and create a new
+    #   If the argument is not a {Flow}, we assume it is an adapter and create
-    #   {Flow} for it.
+    #   a new {Flow} with it.
     # @return [void]
     def []=(index, flow)
       flow = Flow.new(flow) unless flow.is_a?(Flow)
@@ -90,7 +91,7 @@ module Rackstash
     end
     alias size length
 
-    # @return [Array<Flow>] an array of all flow elementswithout any `nil`
+    # @return [Array<Flow>] an array of all flow elements without any `nil`
     #   values
     def to_ary
       @flows.to_a.compact

lib/rackstash/version.rb

@@ -4,7 +4,7 @@
 # of the MIT license. See the LICENSE.txt file for details.
 
 module Rackstash
-  # Version information about Rackstash.
+  # Version information about Rackstash. We follow semantic versioning.
   module Version
     # MAJOR version. It is incremented after incompatible API changes
     MAJOR = 0
@@ -28,6 +28,7 @@ module Rackstash
     end
 
     # @return [String] the Rackstash version as a semver-compliant string
+    # @see http://semver.org/
     def self.to_s
       STRING
     end