add/update YARD documentation

lib/rscons/environment.rb

@@ -2,14 +2,17 @@ require 'set'
 require 'fileutils'
 
 module Rscons
+  # The Environment class is the main programmatic interface to RScons. It
+  # contains a collection of construction variables, options, builders, and
+  # rules for building targets.
   class Environment
+    # [Array] of {Builder} objects.
     attr_reader :builders
 
-    # Initialize a newly constructed Environment object
-    # === Arguments
-    # +variables+ _Hash_ ::
-    #   the variables hash can contain both construction variables, which are
-    #   uppercase strings (such as "CC" or "LDFLAGS"), and rscons options,
+    # Create an Environment object.
+    # @param variables [Hash]
+    #   The variables hash can contain both construction variables, which are
+    #   uppercase strings (such as "CC" or "LDFLAGS"), and RScons options,
     #   which are lowercase symbols (such as :echo).
     def initialize(variables = {})
       @varset = VarSet.new(variables)
@@ -36,6 +39,10 @@ module Rscons
       end
     end
 
+    # Make a copy of the Environment object.
+    # The cloned environment will contain a copy of all environment options,
+    # construction variables, builders, and build directories. It will not
+    # contain a copy of the targets.
     def clone(variables = {})
       env = Environment.new()
       @builders.each do |builder_name, builder|
@@ -54,6 +61,7 @@ module Rscons
       env
     end
 
+    # Add a {Builder} object to the Environment.
     def add_builder(builder)
       @builders[builder.class.short_name] = builder
       var_defs = builder.default_variables(self)
@@ -64,10 +72,16 @@ module Rscons
       end
     end
 
+    # Specify a build directory for this Environment.
+    # Source files from src_dir will produce object files under obj_dir.
     def build_dir(src_dir, obj_dir)
       @build_dirs[src_dir.gsub('\\', '/')] = obj_dir.gsub('\\', '/')
     end
 
+    # Return the file name to be built from source_fname with suffix suffix.
+    # This method takes into account the Environment's build directories.
+    # It also creates any parent directories needed to be able to open and
+    # write to the output file.
     def get_build_fname(source_fname, suffix)
       build_fname = source_fname.set_suffix(suffix).gsub('\\', '/')
       @build_dirs.each do |src_dir, obj_dir|
@@ -77,26 +91,37 @@ module Rscons
       build_fname
     end
 
+    # Access a construction variable or environment option.
+    # @see VarSet#[]
     def [](*args)
       @varset.send(:[], *args)
     end
 
+    # Set a construction variable or environment option.
+    # @see VarSet#[]=
     def []=(*args)
       @varset.send(:[]=, *args)
     end
 
+    # Add a set of construction variables or environment options.
+    # @see VarSet#append
     def append(*args)
       @varset.send(:append, *args)
     end
 
+    # Return a list of target file names
     def targets
       @targets.keys
     end
 
+    # Return a list of sources needed to build target target.
     def target_sources(target)
       @targets[target][:source] rescue nil
     end
 
+    # Build all target specified in the Environment.
+    # When a block is passed to Environment.new, this method is automatically
+    # called after the block returns.
     def process
       cache = Cache.new
       targets_processed = Set.new
@@ -123,10 +148,23 @@ module Rscons
       cache.write
     end
 
+    # Build a command line from the given template, resolving references to
+    # variables using the Environment's construction variables and any extra
+    # variables specified.
+    # @param command_template [Array] template for the command with variable
+    #   references
+    # @param extra_vars [Hash, VarSet] extra variables to use in addition to
+    #   (or replace) the Environment's construction variables when building
+    #   the command
     def build_command(command_template, extra_vars)
       @varset.merge(extra_vars).expand_varref(command_template)
     end
 
+    # Execute a builder command
+    # @param short_desc [String] Message to print if the Environment's :echo
+    #   mode is set to :short
+    # @param command [Array] The command to execute.
+    # @param options [Hash] Optional options to pass to {Kernel#system}.
     def execute(short_desc, command, options = {})
       print_command = proc do
         puts command.map { |c| c =~ /\s/ ? "'#{c}'" : c }.join(' ')
@@ -159,6 +197,10 @@ module Rscons
       end
     end
 
+    # Parse dependencies for a given target from a Makefile.
+    # This method is used internally by RScons builders.
+    # @param mf_fname [String] File name of the Makefile to read.
+    # @param target [String] Name of the target to gather dependencies for.
     def parse_makefile_deps(mf_fname, target)
       deps = []
       buildup = ''