Improve DSL method documentation - close #164

doc/user_guide.md

@@ -1308,10 +1308,10 @@ It iterates through each enabled variant and calls the given block.
 In this example, the block would be called twice, once with the "kde" variant
 active, and the second time with the "gnome" variant active.
 
-Each `env()` call creates an Environment, so two environments are created.
+Each `env` method call creates an Environment, so two environments are created.
 When an Environment is created within a `with_variants` block, the
-Environment's name has the active variant(s) appended to the given Environment
-name (if any), and separated by a "-".
+Environment's build directory name has the active variant(s) keys appended to
+the given Environment name, and separated by a "-".
 
 In this example, a "prog-kde" Environment would be created with build root
 build/prog-kde and -DKDE would be passed to the compiler when compiling each
@@ -1320,6 +1320,29 @@ Next a "prog-gnome" Environment would be created with build root
 build/prog-gnome and -DGNOME would be passed to the compiler when compiling
 the sources.
 
+The key for a variant is the variant's name by default but can be overridden by
+passing a `:key` value to the `variant` method.
+A `nil` value for the `:key` parameter will omit that variant from appearing
+in the environment's build directory name.
+For example:
+
+```ruby
+variant "debug"
+variant "release", key: nil
+
+with_variants do
+  env "prog" do |env|
+  end
+end
+```
+
+In this example, one "prog" environment will be created for the "debug" variant
+with the build directory "prog-debug", and another "prog" environment will be
+created for the "release" variant with the build directory "prog".
+The build directory for the release variant of the "prog" environment is just
+"prog" instead of "prog-release" because the key for the "release" variant is
+set to `nil`.
+
 Variants are enabled by default, but can be disabled by passing a `false` value
 to the `:default` option of the `variant` method.
 For example:

lib/rscons/application.rb

@@ -258,6 +258,14 @@ module Rscons
     #
     # @param name [String]
     #   Variant name.
+    # @param options [Hash]
+    #   Optional parameters.
+    # @option options [String] :default
+    #   Whether the variant is enabled by default (default: true).
+    # @option options [String] :key
+    #   Variant key, used to name an Environment's build directory. If nil,
+    #   this variant will not contribute to the Environment's build directory
+    #   name.
     def variant(name, options = {})
       if @active_variants
         !!@active_variants.find {|variant| variant[:name] == name}
@@ -294,6 +302,15 @@ module Rscons
     end
 
     # Create a variant group.
+    #
+    # @overload variant_group(name, options = {})
+    #   @param name [String]
+    #     Variant group name (optional).
+    #   @param options [Hash]
+    #     Optional variant group parameters.
+    # @overload variant_group(options = {})
+    #   @param options [Hash]
+    #     Optional variant group parameters.
     def variant_group(*args, &block)
       if args.first.is_a?(String)
         name = args.slice!(0)

lib/rscons/script.rb

@@ -289,27 +289,80 @@ module Rscons
       end
 
       # Create or modify a task.
+      #
+      # @overload task(name, options = {}, &block)
+      # @param name [String]
+      #   Task name.
+      # @param options [Hash]
+      #   Optional task attributes.
+      # @option options [Boolean] :autoconf
+      #   Whether to automatically configure before running this task
+      #   (default: true).
+      # @option options [String] :desc
+      #   Description for the task.
+      # @option options [Array<String>] :depends
+      #   Dependencies of the task.
+      # @option options [Array<Task::Param>] :params
+      #   Task parameter definitions.
+      #
+      # The action block given will be invoked by Rscons when the task
+      # executes. It will be passed two arguments:
+      #   1) The Task object.
+      #   2) A Hash of task parameter names and values.
       def task(*args, &block)
         Util.task(*args, &block)
       end
 
       # Define a variant, or within a with_variants block, query if it is
       # active.
-      def variant(*args)
-        Rscons.application.variant(*args)
+      #
+      # @param name [String]
+      #   Variant name.
+      # @param options [Hash]
+      #   Optional parameters.
+      # @option options [String] :default
+      #   Whether the variant is enabled by default (default: true).
+      # @option options [String] :key
+      #   Variant key, used to name an Environment's build directory. If nil,
+      #   this variant will not contribute to the Environment's build directory
+      #   name.
+      def variant(name, options = {})
+        Rscons.application.variant(name, options)
       end
 
       # Check if a variant is enabled.
-      def variant_enabled?(*args)
-        Rscons.application.variant_enabled?(*args)
+      #
+      # This can be used, for example, in a configuration block to omit or
+      # include configuration checks based on which variants have been
+      # configured.
+      #
+      # @param variant_name [String]
+      #   Variant name.
+      #
+      # @return [Boolean]
+      #   Whether the requested variant is enabled.
+      def variant_enabled?(variant_name)
+        Rscons.application.variant_enabled?(variant_name)
       end
 
       # Create a variant group.
+      #
+      # @overload variant_group(name, options = {})
+      #   @param name [String]
+      #     Variant group name (optional).
+      #   @param options [Hash]
+      #     Optional variant group parameters.
+      # @overload variant_group(options = {})
+      #   @param options [Hash]
+      #     Optional variant group parameters.
       def variant_group(*args, &block)
         Rscons.application.variant_group(*args, &block)
       end
 
-      # Iterate through variants.
+      # Iterate through enabled variants.
+      #
+      # The given block is called for each combination of enabled variants
+      # across the defined variant groups.
       def with_variants(&block)
         Rscons.application.enable_variants
         Rscons.application.with_variants(&block)
@@ -349,11 +402,17 @@ module Rscons
     # Top-level DSL available to the Rsconscript.
     class TopLevelDsl < GlobalDsl
       # Set the project name.
+      #
+      # @param project_name [String]
+      #   Project name.
       def project_name(project_name)
         @script.project_name = project_name
       end
 
-      # Whether to automatically configure (default true).
+      # Set whether to automatically configure (default true).
+      #
+      # @param autoconf [Boolean]
+      #   Whether to automatically configure.
       def autoconf(autoconf)
         @script.autoconf = autoconf
       end