Improve documentation for Context and Any classes

src/liquid/any.cr

@@ -7,17 +7,21 @@ module Liquid
     # Returns the raw underlying value.
     getter raw : Type
 
+    # Creates an instance of `Liquid::Any` with a value of nil.
     def initialize
       @raw = nil
     end
 
+    # Creates an instance of `Liquid::Any` that wraps the given value.
     def initialize(@raw : Type)
     end
 
+    # Assumes the underlying value is an `Array` and adds *value* to the array.
     def <<(value : Type) : Array(Any)
       init_raw_to_array_if_nil << Any.new(value)
     end
 
+    # Assumes the underlying value is an `Array` and adds *value* to the array.
     def <<(value : Any) : Array(Any)
       init_raw_to_array_if_nil << value
     end
@@ -83,11 +87,15 @@ module Liquid
       end
     end
 
+    # Assumes the underlying value is a `Hash`and assigns a value at the given *key*.
+    # Raises if the underlying value is not a `Hash`.
     def []=(key : String | Symbol, value : Type) : Type
       init_raw_to_hash_if_nil[key.to_s] = Any.new(value)
       value
     end
 
+    # Assumes the underlying value is a `Hash`and assigns a value at the given *key*.
+    # Raises if the underlying value is not a `Hash`.
     def []=(key : String | Symbol, value : Any) : Any
       init_raw_to_hash_if_nil[key.to_s] = value
     end
@@ -252,17 +260,22 @@ module Liquid
       @raw.inspect(io)
     end
 
+    # Assumes the underlying value is a numerical value, and returns the value with the opposite sign.
     def -
       raw = @raw
       raise InvalidExpression.new("Can't apply '-' operator to #{raw.class.name}") unless raw.is_a?(Number)
 
       Any.new(-raw)
     end
 
+    # Checks that the underlying value is a numerical value, and returns its value.
+    # Returns 0 otherwise.
     def as_number : Number
       as_number? || 0
     end
 
+    # Checks that the underlying value is a numerical value, and returns its value.
+    # Returns `nil` otherwise.
     def as_number?
       raw = @raw
       if raw.is_a?(Number)
@@ -276,6 +289,7 @@ module Liquid
       end
     end
 
+    # Returns a string representation of the underlying value.
     def to_s(io : IO) : Nil
       @raw.to_s(io)
     end
@@ -303,6 +317,7 @@ module Liquid
       !!(@raw || other.raw)
     end
 
+    # Returns true if the underlying value is an `Array` or `String`, and contains *other*, false otherwise.
     def contains?(other : Any) : Bool
       raw = @raw
       return raw.includes?(other) if raw.is_a?(Array(Any))

src/liquid/context.cr

@@ -2,14 +2,19 @@ require "./any"
 require "./blank"
 
 module Liquid
+  # A `Context` object provides the variables used by the `Template` object. These variables are stored
+  # as key-value pairs of type `String`, `Liquid::Any`.
+  #
+  #
   class Context
     # Context error mode.
     enum ErrorMode
-      # Raise exceptions on any error but `UndefinedVariable`, that can be accessed later by `Context#errors`.
+      # Raises exceptions on any error other than `UndefinedVariable`, which are saved and can be
+      # accessed later through `Context#errors`.
       Strict
-      # Like `Lax` mode, but the errors can be accessed later by `Context#errors`.
+      # Similar to `Lax` mode, but the errors can be accessed later through `Context#errors`.
       Warn
-      # Do the best to render something without raising any exceptions.
+      # Attempts to render the template without raising any exceptions.
       Lax
     end
 
@@ -22,9 +27,10 @@ module Liquid
     protected getter filter_options = Hash(String, Any).new(Any.new)
 
     property error_mode : ErrorMode
-    # List of errors found when rendering using this context.
+    # Returns a list of errors found when rendering using this context.
     getter errors = Array(LiquidException).new
 
+    # Creates a new `Context` with the given *error_mode* and *data*.
     def initialize(@error_mode = :lax, @data = Hash(String, Any).new)
       add_builtins
     end
@@ -87,25 +93,29 @@ module Liquid
       get(var)
     end
 
-    # Fetch a variable from context and return nil if the variable isn't found.
+    # Returns the value for the variable given by *var*, or nil if the variable isn't found.
     #
     # This doesn't trigger any exceptions or store any errors if the variable doesn't exists.
     def []?(var : String) : Any?
       @data[var]?
     end
 
+    # Sets the value of *var* to the given *value*.
     def set(var : String, value : Any) : Any
       @data[var] = value
     end
 
+    # Sets the value for *var* to an instance of `Liquid::Any` generated from *value*.
     def set(var : String, value : Any::Type) : Any
       set(var, Any.new(value))
     end
 
+    # Alias for `#set`
     def []=(var, value : Any) : Any
       set(var, value)
     end
 
+    # Alias for `#set`
     def []=(var, value : Any::Type) : Any
       set(var, value)
     end