Document additional public methods

lib/rackstash/fields/array.rb

@@ -12,10 +12,25 @@ module Rackstash
         @raw = []
       end
 
+      # Retrieve a stored value from a given `index`
+      #
+      # @param index [Integer] the index in the array where we fetch the value
+      # @return [Object, nil] the current value at `index` or `nil` if no value
+      #   could be found
       def [](index)
         @raw[index]
       end
 
+      # Set the value at a given index to the supplied value. The value is
+      # normalized before being set.
+      #
+      # You can set nested hashes and arrays here.
+      #
+      # @param index [Integer] the index in the array where we fetch the value
+      # @param value [#call, Object] 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.
+      # @return [void]
       def []=(index, value)
         @raw[index] = normalize(value)
       end
@@ -31,6 +46,7 @@ module Rackstash
         self
       end
 
+      # @return [::Array] deep-transforms the array into a plain Ruby Array
       def as_json(*)
         @raw.map { |value|
           value.is_a?(AbstractCollection) ? value.as_json : value
@@ -39,21 +55,31 @@ module Rackstash
       alias :to_ary :as_json
       alias :to_a :as_json
 
+      # Removes all elements from `self`.
+      #
+      # @return [self]
       def clear
         @raw.clear
         self
       end
 
+      # Appends the elements of `array` to self.
+      #
+      # @param array [Array, ::Array] an array of values. Each value is
+      #   normalized before being added to `self`.
+      # @return [self]
       def concat(array)
         array = Array(normalize(array, wrap: false))
         @raw.concat(array)
         self
       end
 
+      # @return [Boolean] `true` if `self` contain no elements
       def empty?
         @raw.empty?
       end
 
+      # @return [Integer] the number of elements in `self`
       def length
         @raw.length
       end

lib/rackstash/fields/hash.rb

@@ -8,6 +8,8 @@ require 'rackstash/fields/abstract_collection'
 module Rackstash
   module Fields
     class Hash < AbstractCollection
+      # @param forbidden_keys [Set<String>,Array<String>] a list of strings
+      #   which are not allowed to be used as keys in this hash
       def initialize(forbidden_keys: EMPTY_SET)
         @raw = {}
 
@@ -19,6 +21,8 @@ module Rackstash
         end
       end
 
+      # Retrieve a stored value from a given `key`
+      #
       # @param key [#to_s] the key name. We will always use it as a
       #   frozen UTF-8 String.
       # @return [Object, nil] the current value of the field or `nil` if the