added more documentation to get to 100% YARD coverage; fix YARD warnings

lib/rscons/builders/cfile.rb

@@ -7,6 +7,11 @@ module Rscons
     #   env.CFile("parser.tab.cc", "parser.yy")
     #   env.CFile("lex.yy.cc", "parser.ll")
     class CFile < Builder
+      # Return default construction variables for the builder.
+      #
+      # @param env [Environment] The Environment using the builder.
+      #
+      # @return [Hash] Default construction variables for the builder.
       def default_variables(env)
         {
           "YACC" => "bison",
@@ -18,6 +23,16 @@ module Rscons
         }
       end
 
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
       def run(target, sources, cache, env, vars)
         vars = vars.merge({
           "_TARGET" => target,

lib/rscons/builders/disassemble.rb

@@ -2,6 +2,11 @@ module Rscons
   module Builders
     # The Disassemble builder produces a disassembly listing of a source file.
     class Disassemble < Builder
+      # Return default construction variables for the builder.
+      #
+      # @param env [Environment] The Environment using the builder.
+      #
+      # @return [Hash] Default construction variables for the builder.
       def default_variables(env)
         {
           "OBJDUMP" => "objdump",
@@ -10,6 +15,16 @@ module Rscons
         }
       end
 
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
       def run(target, sources, cache, env, vars)
         vars = vars.merge("_SOURCES" => sources)
         command = env.build_command("${DISASM_CMD}", vars)

lib/rscons/builders/library.rb

@@ -2,6 +2,11 @@ module Rscons
   module Builders
     # A default Rscons builder that produces a static library archive.
     class Library < Builder
+      # Return default construction variables for the builder.
+      #
+      # @param env [Environment] The Environment using the builder.
+      #
+      # @return [Hash] Default construction variables for the builder.
       def default_variables(env)
         {
           'AR' => 'ar',
@@ -11,6 +16,16 @@ module Rscons
         }
       end
 
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
       def run(target, sources, cache, env, vars)
         # build sources to linkable objects
         objects = env.build_sources(sources, env.expand_varref(["${OBJSUFFIX}", "${LIBSUFFIX}"], vars).flatten, cache, vars)

lib/rscons/builders/object.rb

@@ -3,6 +3,7 @@ module Rscons
     # A default Rscons builder which knows how to produce an object file from
     # various types of source files.
     class Object < Builder
+      # Mapping of known sources from which to build object files.
       KNOWN_SUFFIXES = {
         "AS" => "ASSUFFIX",
         "CC" => "CSUFFIX",
@@ -10,6 +11,11 @@ module Rscons
         "DC" => "DSUFFIX",
       }
 
+      # Return default construction variables for the builder.
+      #
+      # @param env [Environment] The Environment using the builder.
+      #
+      # @return [Hash] Default construction variables for the builder.
       def default_variables(env)
         {
           'OBJSUFFIX' => '.o',
@@ -51,12 +57,32 @@ module Rscons
         }
       end
 
+      # Return whether this builder object is capable of producing a given target
+      # 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 env [Environment] The Environment.
+      #
+      # @return [Boolean]
+      #   Whether this builder object is capable of producing a given target
+      #   file name from a given source file name.
       def produces?(target, source, env)
         target.end_with?(*env['OBJSUFFIX']) and KNOWN_SUFFIXES.find do |compiler, suffix_var|
           source.end_with?(*env[suffix_var])
         end
       end
 
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
       def run(target, sources, cache, env, vars)
         vars = vars.merge({
           '_TARGET' => target,

lib/rscons/builders/preprocess.rb

@@ -2,12 +2,27 @@ module Rscons
   module Builders
     # The Preprocess builder invokes the C preprocessor
     class Preprocess < Builder
+      # Return default construction variables for the builder.
+      #
+      # @param env [Environment] The Environment using the builder.
+      #
+      # @return [Hash] Default construction variables for the builder.
       def default_variables(env)
         {
           "CPP_CMD" => ["${_PREPROCESS_CC}", "-E", "-o", "${_TARGET}", "-I${CPPPATH}", "${CPPFLAGS}", "${CFLAGS}", "${_SOURCES}"],
         }
       end
 
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
       def run(target, sources, cache, env, vars)
         pp_cc = if sources.find {|s| s.end_with?(*env.expand_varref("${CXXSUFFIX}", vars))}
                   "${CXX}"

lib/rscons/builders/program.rb

@@ -3,6 +3,11 @@ module Rscons
     # A default Rscons builder that knows how to link object files into an
     # executable program.
     class Program < Builder
+      # Return default construction variables for the builder.
+      #
+      # @param env [Environment] The Environment using the builder.
+      #
+      # @return [Hash] Default construction variables for the builder.
       def default_variables(env)
         {
           'OBJSUFFIX' => '.o',
@@ -18,6 +23,20 @@ module Rscons
         }
       end
 
+      # Create a BuildTarget object for this build target.
+      #
+      # The build target filename is given a ".exe" suffix if Rscons is
+      # executing on a Windows platform and no other suffix is given.
+      #
+      # @param options [Hash] Options to create the BuildTarget with.
+      # @option options [Environment] :env
+      #   The Environment.
+      # @option options [String] :target
+      #   The user-supplied target name.
+      # @option options [Array<String>] :sources
+      #   The user-supplied source file name(s).
+      #
+      # @return [BuildTarget]
       def create_build_target(options)
         my_options = options.dup
         unless my_options[:target] =~ /\./
@@ -26,6 +45,16 @@ module Rscons
         super(my_options)
       end
 
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
       def run(target, sources, cache, env, vars)
         # build sources to linkable objects
         objects = env.build_sources(sources, env.expand_varref(["${OBJSUFFIX}", "${LIBSUFFIX}"], vars).flatten, cache, vars)