[Sass] Convert Sass::Tree::Node docs to YARD.

lib/sass/tree/node.rb

@@ -1,16 +1,51 @@
 module Sass
+  # A namespace for nodes in the Sass parse tree.
+  #
+  # The Sass parse tree has two states.
+  # When it's first parsed, it has nodes for mixin definitions
+  # and for loops and so forth,
+  # in addition to nodes for CSS rules and properties.
+  #
+  # However, {Node#perform} returns a different sort of tree.
+  # This tree maps more closely to the resulting CSS document
+  # than it does to the original Sass document.
+  # It still has nodes for CSS rules and properties,
+  # but it doesn't have any dynamic-generation-related nodes.
+  #
+  # Nodes that only appear in the pre-perform state are called **dynamic nodes**;
+  # those that appear in both states are called **static nodes**.
   module Tree
+    # This class doubles as the root node of the parse tree
+    # and the superclass of all other parse-tree nodes.
     class Node
+      # The child nodes of this node.
+      #
+      # @return [Array<Node>]
       attr_accessor :children
+
+      # The line of the document on which this node appeared.
+      #
+      # @return [Fixnum]
       attr_accessor :line
+
+      # The name of the document on which this node appeared.
+      #
+      # @return [String]
       attr_accessor :filename
 
+      # @param options [Hash<Symbol, Object>] An options hash;
+      #   see [the Sass options documentation](../../Sass.html#sass_options)
       def initialize(options)
         @options = options
         @style = options[:style]
         @children = []
       end
 
+      # Appends a child to the node.
+      #
+      # @param child [Node] The child node
+      # @raise [Sass::SyntaxError] if `child` is invalid
+      # @see #invalid_child?
       def <<(child)
         if msg = invalid_child?(child)
           raise Sass::SyntaxError.new(msg, child.line)
@@ -18,15 +53,34 @@ module Sass
         @children << child
       end
 
-      # We need this because Node duck types as an Array in engine.rb
+      # Return the last child node.
+      #
+      # We need this because {Node} duck types as an Array for {Sass::Engine}.
+      #
+      # @return [Node] The last child node
       def last
         children.last
       end
 
+      # Compares this node and another object (only other {Node}s will be equal).
+      # This does a structural comparison;
+      # if the contents of the nodes and all the child nodes are equivalent,
+      # then the nodes are as well.
+      #
+      # @param other [Object] The object to compare with
+      # @return [Boolean] Whether or not this node and the other object
+      #   are the same
       def ==(other)
         self.class == other.class && other.children == children
       end
 
+      # Computes the CSS corresponding to this Sass tree.
+      #
+      # Only static-node subclasses need to implement \{#to\_s}.
+      #
+      # @return [String] The resulting CSS
+      # @raise [Sass::SyntaxError] if some element of the tree is invalid
+      # @see Sass::Tree
       def to_s
         result = String.new
         children.each do |child|
@@ -41,6 +95,21 @@ module Sass
         @style == :compressed ? result+"\n" : result[0...-1]
       end
 
+      # Runs the dynamic Sass code:
+      # mixins, variables, control structures, and so forth.
+      # This doesn't modify this node or any of its children.
+      #
+      # \{#perform} shouldn't be overridden directly;
+      # if you want to return a new node (or list of nodes),
+      # override \{#\_perform};
+      # if you want to destructively modify this node,
+      # override \{#perform!}.
+      #
+      # @param environment [Sass::Environment] The lexical environment containing
+      #   variable and mixin values
+      # @return [Node] The resulting tree of static nodes
+      # @raise [Sass::SyntaxError] if some element of the tree is invalid
+      # @see Sass::Tree
       def perform(environment)
         _perform(environment)
       rescue Sass::SyntaxError => e
@@ -50,20 +119,47 @@ module Sass
 
       protected
 
+      # Runs any dynamic Sass code in this particular node.
+      # This doesn't modify this node or any of its children.
+      #
+      # @param environment [Sass::Environment] The lexical environment containing
+      #   variable and mixin values
+      # @return [Node, Array<Node>] The resulting static nodes
+      # @see #perform
+      # @see Sass::Tree
       def _perform(environment)
         node = dup
         node.perform!(environment)
         node
       end
 
+      # Destructively runs dynamic Sass code in this particular node.
+      # This *does* modify this node,
+      # but will be run non-destructively by \{#\_perform\}.
+      #
+      # @param environment [Sass::Environment] The lexical environment containing
+      #   variable and mixin values
+      # @see #perform
       def perform!(environment)
         self.children = perform_children(Environment.new(environment))
       end
 
+      # Non-destructively runs \{#perform} on all children of the current node.
+      #
+      # @param environment [Sass::Environment] The lexical environment containing
+      #   variable and mixin values
+      # @return [Array<Node>] The resulting static nodes
       def perform_children(environment)
         children.map {|c| c.perform(environment)}.flatten
       end
 
+      # Replaces SassScript in a chunk of text (via `#{}`)
+      # with the resulting value.
+      #
+      # @param text [String] The text to interpolate
+      # @param environment [Sass::Environment] The lexical environment containing
+      #   variable and mixin values
+      # @return [String] The interpolated text
       def interpolate(text, environment)
         res = ''
         rest = Haml::Shared.handle_interpolation text do |scan|
@@ -80,17 +176,24 @@ module Sass
         res + rest
       end
 
+      # @see Haml::Shared.balance
+      # @raise [Sass::SyntaxError] if the brackets aren't balanced
       def balance(*args)
         res = Haml::Shared.balance(*args)
         return res if res
         raise Sass::SyntaxError.new("Unbalanced brackets.", line)
       end
 
-      private
-
-      # This method should be overridden by subclasses to return an error message
-      # if the given child node is invalid,
-      # and false or nil otherwise.
+      # Returns an error message if the given child node is invalid,
+      # and false otherwise.
+      #
+      # By default, all child nodes are valid.
+      # This is expected to be overriden by subclasses
+      # for which some children are invalid.
+      #
+      # @param child [Node] A potential child node
+      # @return [Boolean, String] Whether or not the child node is valid,
+      #   as well as the error message to display if it is invalid
       def invalid_child?(child)
         false
       end