improve documentation based on feedback from Inch CI 👍

lib/cadenza/block_hierarchy.rb

@@ -16,7 +16,9 @@ def initialize(data=nil)
          merge(data) if data
       end
 
-      # @return [Array] the inheritance chain for the given block name
+      # fetches the inheritance chain for the given block name.  if the block 
+      # name is undefined then an empty array is returned.
+      # @return [Array] the inheritance chain
       def fetch(block_name)
          @names[block_name.to_s] || []
       end

lib/cadenza/library/functions.rb

@@ -12,30 +12,57 @@ def self.const_missing(const_name)
    module Library
       module Functions
 
+         # @!attribute [r] functions
+         # @return [Hash] the function names mapped to their implementing procs
          # @deprecated Use {#functions} instead
          def functional_variables
             warn "`#functional_variables` has been deprecated.  Use `#functions` instead."
             functions
          end
 
+         # looks up the function by name
+         # 
+         # @raise [FunctionNotDefinedError] if the function can not be found
+         # @param [Symbol] name the name of the function to look up
+         # @return [Proc] the function implementation
          # @deprecated Use {#lookup_function} instead
          def lookup_functional_variable(name)
             warn "`#lookup_functional_variable` has been deprecated.  Use `#lookup_function` instead."
             lookup_function(name)
          end
-
+
+         # defines a function proc with the given name
+         #
+         # @param [Symbol] name the name for the template to use for this variable
+         # @yield [Context, *args] the block will receive the context object and a
+         #                         variable number of arguments passed to the variable.
+         # @return nil
          # @deprecated Use {#define_function} instead
          def define_functional_variable(name, &block)
             warn "`#define_functional_variable` has been deprecated.  Use `#define_function` instead."
             define_function(name, &block)
          end
 
-         # @deprecated Use {#alias_functional_variable} instead
+         # creates an alias of the given function name under a different name 
+         #
+         # @raise [FunctionNotDefinedError] if the original function name isn't defined
+         # @param [Symbol] original_name the original name of the function
+         # @param [Symbol] alias_name the new name of the function
+         # @return nil
+         # @deprecated Use {#alias_function} instead
          def alias_functional_variable(original_name, alias_name)
             warn "`#alias_functional_variable` has been deprecated. Use `#alias_function` instead."
             alias_function(original_name, alias_name)
          end
 
+         # calls the defined function proc with the given parameters and returns 
+         # the result.
+         #
+         # @raise [FunctionNotDefinedError] if the named function doesn't exist
+         # @param [Symbol] name the name of the function to evaluate
+         # @param [Array] params a list of parameters to pass to the function
+         #                block when calling it
+         # @return [Object] the result of  evaluating the function
          # @deprecated Use {#evaluate_function} instead
          def evaluate_functional_variable(name, context, params=[])
             warn "`#evaluate_functional_variable` has been deprecated. Use `#evaluate_function` instead."

lib/cadenza/nodes/boolean_inverse_node.rb

@@ -9,7 +9,7 @@ class BooleanInverseNode
       attr_accessor :expression
 
       # creates a new {BooleanInverseNode} with the given expression
-      # @param [OperationNode] the node this one will invert
+      # @param [OperationNode] expression the node this one will invert
       def initialize(expression)
          @expression = expression
       end

lib/cadenza/nodes/filtered_value_node.rb

@@ -13,7 +13,7 @@ class FilteredValueNode
       attr_accessor :filters
 
       # creates a new {FilteredValueNode}.
-      # @param [String] identifier see {#identifier}
+      # @param [String] value see {#value}
       # @param [Array] filters see {#filters}
       def initialize(value, filters=[])
          @value = value