[Sass] Convert Sass::Environment docs to YARD.

We need to add a special YARD handler for some metaprogramming.

Rakefile

@@ -101,6 +101,7 @@ begin
     t.files = files.to_a
 
     t.options << '-r' << 'README.md' << '-m' << 'maruku' << '--protected'
+    t.options += FileList.new('yard/*.rb').to_a.map {|f| ['-e', f]}.flatten
   end
 
   task :doc => :yardoc

lib/sass/environment.rb

@@ -1,7 +1,25 @@
 module Sass
+  # The lexical environment for SassScript.
+  # This keeps track of variable and mixin definitions.
+  #
+  # A new environment is created for each level of Sass nesting.
+  # This allows variables to be lexically scoped.
+  # The new environment refers to the environment in the upper scope,
+  # so it has access to variables defined in enclosing scopes,
+  # but new variables are defined locally.
+  #
+  # Environment also keeps track of the {Engine} options
+  # so that they can be made available to {Sass::Functions}.
   class Environment
+    # The enclosing environment,
+    # or nil if this is the global environment.
+    #
+    # @return [Environment]
     attr_reader :parent
 
+    # @param parent [Environment] See \{#parent}
+    # @param options [Hash<Symbol, Object>] An options hash;
+    #   see [the Sass options documentation](../Sass.html#sass_options)
     def initialize(parent = nil, options = nil)
       @vars = {}
       @mixins = {}
@@ -9,30 +27,45 @@ module Sass
       @options = options
     end
 
+    # The options hash.
+    # See [the Sass options documentation](../Sass.html#sass_options).
+    #
+    # @return [Hash<Symbol, Object>]
     def options
       @options || (parent && parent.options) || {}
     end
 
-    def self.inherited_hash(name)
-      class_eval <<RUBY, __FILE__, __LINE__ + 1
-        def #{name}(name)
-          @#{name}s[name] || @parent && @parent.#{name}(name)
-        end
+    class << self
+      private
 
-        def set_#{name}(name, value)
-          if @parent.nil? || @#{name}s.include?(name)
-            @#{name}s[name] = value
-          else
-            @parent.set_#{name}(name, value)
+      # Note: when updating this,
+      # update haml/yard/inherited_hash.rb as well.
+      def inherited_hash(name)
+        class_eval <<RUBY, __FILE__, __LINE__ + 1
+          def #{name}(name)
+            @#{name}s[name] || @parent && @parent.#{name}(name)
           end
-        end
 
-        def set_local_#{name}(name, value)
-          @#{name}s[name] = value
-        end
+          def set_#{name}(name, value)
+            if @parent.nil? || @#{name}s.include?(name)
+              @#{name}s[name] = value
+            else
+              @parent.set_#{name}(name, value)
+            end
+          end
+
+          def set_local_#{name}(name, value)
+            @#{name}s[name] = value
+          end
 RUBY
+      end
     end
+
+    # variable
+    # Script::Literal
     inherited_hash :var
+    # mixin
+    # Engine::Mixin
     inherited_hash :mixin
   end
 end

yard/inherited_hash.rb

@@ -0,0 +1,44 @@
+class InheritedHashHandler < YARD::Handlers::Base
+  handles /\Ainherited_hash(\s|\()/
+
+  def process
+    hash_name = tokval(statement.tokens[2])
+    name = statement.comments.first.strip
+    type = statement.comments[1].strip
+
+    register(MethodObject.new(namespace, hash_name, scope)) do |o|
+      o.docstring = [
+        "Gets a #{name} from this {Environment} or one of its \\{#parent}s.",
+        "@param name [String] The name of the #{name}",
+        "@return [#{type}] The #{name} value",
+      ]
+      o.signature = true
+      o.parameters = ["name"]
+    end
+
+    register(MethodObject.new(namespace, "set_#{hash_name}", scope)) do |o|
+      o.docstring = [
+        "Sets a #{name} in this {Environment} or one of its \\{#parent}s.",
+        "If the #{name} is already defined in some environment,",
+        "that one is set; otherwise, a new one is created in this environment.",
+        "@param name [String] The name of the #{name}",
+        "@param value [#{type}] The value of the #{name}",
+        "@return [#{type}] `value`",
+      ]
+      o.signature = true
+      o.parameters = ["name", "value"]
+    end
+
+    register(MethodObject.new(namespace, "set_local_#{hash_name}", scope)) do |o|
+      o.docstring = [
+        "Sets a #{name} in this {Environment}.",
+        "Ignores any parent environments.",
+        "@param name [String] The name of the #{name}",
+        "@param value [#{type}] The value of the #{name}",
+        "@return [#{type}] `value`",
+      ]
+      o.signature = true
+      o.parameters = ["name", "value"]
+    end
+  end
+end