From d5e0475e6c626fdd2cf1dcf6d3cc53ae6d3e4d53 Mon Sep 17 00:00:00 2001 From: Josh Holtrop Date: Tue, 21 Oct 2014 17:00:38 -0400 Subject: [PATCH] minor documentation improvements --- lib/rscons.rb | 4 ++ lib/rscons/builder.rb | 4 +- lib/rscons/builders/command.rb | 6 ++- lib/rscons/builders/object.rb | 2 +- lib/rscons/builders/simple_builder.rb | 4 +- lib/rscons/cache.rb | 28 +++++++++++--- lib/rscons/environment.rb | 56 +++++++++++++++++---------- lib/rscons/varset.rb | 2 +- 8 files changed, 74 insertions(+), 32 deletions(-) diff --git a/lib/rscons.rb b/lib/rscons.rb index 30b3306..bc0fa3c 100644 --- a/lib/rscons.rb +++ b/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] Command used to execute commands. + # + # @return [Array] Command used to execute commands. def self.command_executer=(val) @@command_executer = val end diff --git a/lib/rscons/builder.rb b/lib/rscons/builder.rb index 4868552..265ceed 100644 --- a/lib/rscons/builder.rb +++ b/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] diff --git a/lib/rscons/builders/command.rb b/lib/rscons/builders/command.rb index 5cef156..0ee4192 100644 --- a/lib/rscons/builders/command.rb +++ b/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. # diff --git a/lib/rscons/builders/object.rb b/lib/rscons/builders/object.rb index 1656b3d..6d7bd78 100644 --- a/lib/rscons/builders/object.rb +++ b/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] diff --git a/lib/rscons/builders/simple_builder.rb b/lib/rscons/builders/simple_builder.rb index 50a31dc..ae21f05 100644 --- a/lib/rscons/builders/simple_builder.rb +++ b/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. diff --git a/lib/rscons/cache.rb b/lib/rscons/cache.rb index 6079010..385e99d 100644 --- a/lib/rscons/cache.rb +++ b/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 command [String, Array] The command used to build the target. - # @param deps [Array] List of the target's dependency files. + # @param targets [String, Array] The name(s) of the target file(s). + # @param command [String, Array, Hash] + # 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] 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 command [String, Array] The command used to build the target. - # @param deps [Array] List of dependencies for the target. + # @param targets [String, Array] The name of the target(s) built. + # @param command [String, Array, Hash] + # 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] List of dependencies for the target. # @param env [Environment] The {Rscons::Environment}. # # @return [void] diff --git a/lib/rscons/environment.rb b/lib/rscons/environment.rb index dc5da90..d5f8ea4 100644 --- a/lib/rscons/environment.rb +++ b/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 obj_dir [String] Path to the object directory. + # @param src_dir [String, Regexp] + # 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 - def append(*args) - @varset.append(*args) + # @param values [VarSet, Hash] New set of variables. + # + # @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 suffixes [Array] List of suffixes to try to convert source files into. + # @param sources [Array] List of source files to build. + # @param suffixes [Array] + # 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] 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 - # merging them directly to the Environment. They can be merged with - # {#merge_flags}. The {#parse_flags!} version immediately merges the parsed - # flags as well. + # For {#parse_flags}, the parsed construction variables are returned in a + # Hash instead of merging them directly to the Environment. They can be + # merged with {#merge_flags}. The {#parse_flags!} version immediately + # merges the parsed flags as well. # # Example: # # Import FreeType build options diff --git a/lib/rscons/varset.rb b/lib/rscons/varset.rb index 0bf6bb6..4f8c6d6 100644 --- a/lib/rscons/varset.rb +++ b/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)