minor documentation improvements

lib/rscons.rb

@@ -33,6 +33,8 @@ module Rscons
   class BuildError < RuntimeError; end
 
   # Remove all generated files.
+  #
+  # @return [void]
   def self.clean
     cache = Cache.instance
     # remove all built files
@@ -121,6 +123,8 @@ module Rscons
   # Set the command executer array.
   #
   # @param val [Array<String>] Command used to execute commands.
+  #
+  # @return [Array<String>] Command used to execute commands.
   def self.command_executer=(val)
     @@command_executer = val
   end

lib/rscons/builder.rb

@@ -9,6 +9,8 @@ module Rscons
     # Return the name of the builder.
     #
     # If not overridden this defaults to the last component of the class name.
+    #
+    # @return [String] The name of the builder.
     def name
       self.class.name.split(":").last
     end
@@ -44,7 +46,7 @@ module Rscons
     # file name from a given source file name.
     #
     # @param target [String] The target file name.
-    # @param source [String, Array] The source file name(s).
+    # @param source [String] The source file name.
     # @param env [Environment] The Environment.
     #
     # @return [Boolean]

lib/rscons/builders/command.rb

@@ -3,9 +3,11 @@ module Rscons
     # Execute a command that will produce the given target based on the given
     # sources.
     #
-    # Example::
+    # @since 1.8.0
+    #
+    # Example:
     #   env.Command("docs.html", "docs.md",
-    #       CMD => ['pandoc', '-fmarkdown', '-thtml', '-o${_TARGET}', '${_SOURCES}'])
+    #               CMD => %w[pandoc -fmarkdown -thtml -o${_TARGET} ${_SOURCES}])
     class Command < Builder
       # Run the builder to produce a build target.
       #

lib/rscons/builders/object.rb

@@ -62,7 +62,7 @@ module Rscons
       # file name from a given source file name.
       #
       # @param target [String] The target file name.
-      # @param source [String, Array] The source file name(s).
+      # @param source [String] The source file name.
       # @param env [Environment] The Environment.
       #
       # @return [Boolean]

lib/rscons/builders/simple_builder.rb

@@ -2,8 +2,10 @@ module Rscons
   module Builders
     # A Generic builder class whose name and operation is defined at
     # instantiation.
+    #
+    # @since 1.8.0
     class SimpleBuilder < Builder
-      # The name of this builder when registered in an environment
+      # @return [String] The name of this builder.
       attr_reader :name
 
       # Create a new builder with the given name and action.

lib/rscons/cache.rb

@@ -63,17 +63,23 @@ module Rscons
     end
 
     # Remove the cache file.
+    #
+    # @return [void]
     def clear
       FileUtils.rm_f(CACHE_FILE)
       initialize!
     end
 
     # Clear the cached file checksums.
+    #
+    # @return [void]
     def clear_checksum_cache!
       @lookup_checksums = {}
     end
 
     # Write the cache to disk to be loaded next time.
+    #
+    # @return [void]
     def write
       if @dirty || (@cache["version"] != VERSION)
         @cache["version"] = VERSION
@@ -86,9 +92,14 @@ module Rscons
 
     # Check if target(s) are up to date.
     #
-    # @param targets [String, Array] The name(s) of the target file(s).
+    # @param targets [String, Array<String>] The name(s) of the target file(s).
-    # @param command [String, Array] The command used to build the target.
+    # @param command [String, Array, Hash]
-    # @param deps [Array] List of the target's dependency files.
+    #   The command used to build the target. The command parameter can
+    #   actually be a String, Array, or Hash and could contain information
+    #   other than just the actual command used to build the target. For the
+    #   purposes of the Cache, any difference in the command argument will
+    #   trigger a rebuild.
+    # @param deps [Array<String>] List of the target's dependency files.
     # @param env [Environment] The Rscons::Environment.
     # @param options [Hash] Optional options.
     # @option options [Boolean] :strict_deps
@@ -148,9 +159,14 @@ module Rscons
 
     # Store cache information about target(s) built by a builder.
     #
-    # @param targets [String, Array] The name of the target(s) built.
+    # @param targets [String, Array<String>] The name of the target(s) built.
-    # @param command [String, Array] The command used to build the target.
+    # @param command [String, Array, Hash]
-    # @param deps [Array] List of dependencies for the target.
+    #   The command used to build the target. The command parameter can
+    #   actually be a String, Array, or Hash and could contain information
+    #   other than just the actual command used to build the target. For the
+    #   purposes of the Cache, any difference in the command argument will
+    #   trigger a rebuild.
+    # @param deps [Array<String>] List of dependencies for the target.
     # @param env [Environment] The {Rscons::Environment}.
     #
     # @return [void]

lib/rscons/environment.rb

@@ -10,7 +10,7 @@ module Rscons
     # @return [Hash] Set of !{"builder_name" => builder_object} pairs.
     attr_reader :builders
 
-    # :command, :short, or :off
+    # @return [Symbol] :command, :short, or :off
     attr_accessor :echo
 
     # @return [String, nil] The build root.
@@ -79,7 +79,7 @@ module Rscons
     #
     # Any options that #initialize receives can also be specified here.
     #
-    # @return a new {Environment} object.
+    # @return [Environment] The newly created {Environment} object.
     def clone(options = {})
       clone = options[:clone] || Set[:variables, :builders]
       clone = Set[:variables, :builders, :build_root, :build_dirs, :build_hooks] if clone == :all
@@ -121,11 +121,17 @@ module Rscons
     # Add a {Builder} object to the Environment.
     #
     # @overload add_builder(builder)
-    #   Registers a builder with the environment
+    #
+    #   Add the given builder to the Environment.
+    #
     #   @param builder [Builder] An instance of the builder to register.
     #
     # @overload add_builder(builder,&action)
-    #   Register a new {Builders::SimpleBuilder} with the environment.
+    #
+    #   Create a new {Builders::SimpleBuilder} instance and add it to the
+    #   environment.
+    #
+    #   @since 1.8.0
     #
     #   @param builder [String,Symbol]
     #     The name of the builder to add.
@@ -133,7 +139,7 @@ module Rscons
     #   @param action [Block]
     #     A block that will be called when the builder is executed to generate
     #     a target file. The provided block should have the same prototype as
-    #     {Rscons::Builder#run}
+    #     {Rscons::Builder#run}.
     #
     # @return [void]
     def add_builder(builder, &action)
@@ -200,8 +206,13 @@ module Rscons
     #
     # Source files from src_dir will produce object files under obj_dir.
     #
-    # @param src_dir [String, Regexp] Path to the source directory.
+    # @param src_dir [String, Regexp]
-    # @param obj_dir [String] Path to the object directory.
+    #   Path to the source directory. If a Regexp is given, it will be matched
+    #   to source file names.
+    # @param obj_dir [String]
+    #   Path to the object directory. If a Regexp is given as src_dir, then
+    #   obj_dir can contain backreferences to groups matched from the source
+    #   file name.
     #
     # @return [void]
     def build_dir(src_dir, obj_dir)
@@ -239,25 +250,27 @@ module Rscons
       build_fname
     end
 
-    # Access a construction variable or environment option.
+    # Get a construction variable's value.
     #
     # @see VarSet#[]
     def [](*args)
       @varset.send(:[], *args)
     end
 
-    # Set a construction variable or environment option.
+    # Set a construction variable's value.
     #
     # @see VarSet#[]=
     def []=(*args)
       @varset.send(:[]=, *args)
     end
 
-    # Add a set of construction variables or environment options.
+    # Add a set of construction variables to the Environment.
     #
-    # @see VarSet#append
+    # @param values [VarSet, Hash] New set of variables.
-    def append(*args)
+    #
-      @varset.append(*args)
+    # @return [void]
+    def append(values)
+      @varset.append(values)
     end
 
     # Build all build targets specified in the Environment.
@@ -303,6 +316,8 @@ module Rscons
     end
 
     # Clear all targets registered for the Environment.
+    #
+    # @return [void]
     def clear_targets
       @targets = {}
     end
@@ -426,8 +441,9 @@ module Rscons
     #
     # This method is used internally by Rscons builders.
     #
-    # @param sources [Array] List of source files to build.
+    # @param sources [Array<String>] List of source files to build.
-    # @param suffixes [Array] List of suffixes to try to convert source files into.
+    # @param suffixes [Array<String>]
+    #   List of suffixes to try to convert source files into.
     # @param cache [Cache] The Cache.
     # @param vars [Hash] Extra variables to pass to the builder.
     #
@@ -456,7 +472,7 @@ module Rscons
     #
     # @param builder [Builder] The Builder to use.
     # @param target [String] The target output file.
-    # @param sources [Array] List of source files.
+    # @param sources [Array<String>] List of source files.
     # @param cache [Cache] The Cache.
     # @param vars [Hash] Extra variables to pass to the builder.
     #
@@ -522,10 +538,10 @@ module Rscons
     # Parse command-line flags for compilation/linking options into separate
     # construction variables.
     #
-    # The parsed construction variables are returned in a Hash instead of
+    # For {#parse_flags}, the parsed construction variables are returned in a
-    # merging them directly to the Environment. They can be merged with
+    # Hash instead of merging them directly to the Environment. They can be
-    # {#merge_flags}. The {#parse_flags!} version immediately merges the parsed
+    # merged with {#merge_flags}. The {#parse_flags!} version immediately
-    # flags as well.
+    # merges the parsed flags as well.
     #
     # Example:
     #   # Import FreeType build options

lib/rscons/varset.rb

@@ -58,7 +58,7 @@ module Rscons
     #
     # @param values [VarSet, Hash] New set of variables.
     #
-    # @return [self]
+    # @return [VarSet] Returns self.
     def append(values)
       coa!
       if values.is_a?(VarSet)