Document the remaining components

Author: randycoulman

lib/jujube/components/builders.rb

@@ -4,11 +4,12 @@ module Components
     # Helper methods for creating builder components.
     module Builders
 
-      # Define a `shell` builder for a job.
+      # Specify a `shell` builder for a job.
       #
       # See {http://ci.openstack.org/jenkins-job-builder/builders.html#builders.shell}.
       #
       # @param command [String] The shell command to execute.
+      # @return [Hash] The specification for the component.
       def shell(command)
         {'shell' => command}
       end

lib/jujube/components/macros.rb

@@ -5,25 +5,25 @@ module Components
     module Macros
       include Jujube::Utils
 
-      # A macro that defines methods that generate a standard component.  A standard
-      # component has a name and a `Hash` of named options.  The names and all option
+      private
+
+      # A macro that defines a standard component.  A standard
+      # component has a name and a `Hash` of named options.  The name and all option
       # keys are {#canonicalize}d.
       #
-      # @param names [Array<Symbol>] The names of the methods to generate.
-      def standard_component(*names)
-        named_config(*names)
+      # @param name [Symbol] The name of the component to generate.
+      def standard_component(name)
+        named_config(name)
       end
 
       # A macro that defines methods that generate a standard named
       # configuration.  A standard named configuration has a name and a `Hash`
       # of named options.  The names and all option keys are {#canonicalize}d.
       #
-      # @param names [Array<Symbol>] Symbols naming the methods to generate.
-      def named_config(*names)
-        names.each do |name|
-          define_method(name) do |options = {}|
-            to_config(canonicalize(name), options)
-          end
+      # @param name [Symbol] The name of the method to generate.
+      def named_config(name)
+        define_method(name) do |options = {}|
+          to_config(canonicalize(name), options)
         end
       end
     end

lib/jujube/components/parameters.rb

@@ -6,35 +6,38 @@ module Parameters
 
       # @!group Matrix Axes
 
-      # Define a `label-expression` axis for a matrix job.
+      # Specify a `label-expression` axis for a matrix job.
       #
       # See {http://ci.openstack.org/jenkins-job-builder/project_matrix.html}.
       #
       # @param name [Symbol, String] The name of the axis.
       # @param values [Array<String>] The values of the axis.
+      # @return [Hash] The specification for the axis.
       def label_expression(name, values)
         axis(name, values, :label_expression)
       end
 
-      # Define a `slave` axis for a matrix job.
+      # Specify a `slave` axis for a matrix job.
       #
       # See {http://ci.openstack.org/jenkins-job-builder/project_matrix.html}.
       #
       # @param name [Symbol, String] The name of the axis.
       # @param values [Array<String>] The values of the axis.
+      # @return [Hash] The specification for the axis.
       def slave(name, values)
         axis(name, values, :slave)
       end
 
       private
 
-      # Define an axis for a matrix job.
+      # Specify an axis for a matrix job.
       #
       # See {http://ci.openstack.org/jenkins-job-builder/project_matrix.html}.
       #
       # @param name [Symbol, String] The name of the axis.
       # @param values [Array<String>] The values of the axis.
       # @param type [Symbol, String] The axis type.
+      # @return [Hash] The specification for the axis.
       def axis(name, values, type)
         options = {type: canonicalize(type), name: canonicalize(name), values: values}
         to_config("axis", options)

lib/jujube/components/publishers.rb

@@ -5,9 +5,61 @@ module Components
     module Publishers
       extend Macros
 
-      standard_component :archive, :cppcheck, :email_ext, :ircbot, :junit, :trigger
+      # @!method archive(options = {})
+      # Specify an `archive` component for a job.
+      #
+      # See {http://ci.openstack.org/jenkins-job-builder/publishers.html#publishers.archive}.
+      #
+      # @param options [Hash] The configuration options for the component.
+      # @return [Hash] The specification for the component.
+      standard_component :archive
+
+      # @!method cppcheck(options = {})
+      # Specify a `cppcheck` component for a job.
+      #
+      # See {http://ci.openstack.org/jenkins-job-builder/publishers.html#publishers.cppcheck}.
+      #
+      # @param options [Hash] The configuration options for the component.
+      # @return [Hash] The specification for the component.
+      standard_component :cppcheck
+
+      # @!method email_ext(options = {})
+      # Specify an `email-ext` component for a job.
+      #
+      # See {http://ci.openstack.org/jenkins-job-builder/publishers.html#publishers.email-ext}.
+      #
+      # @param options [Hash] The configuration options for the component.
+      # @return [Hash] The specification for the component.
+      standard_component :email_ext
+
+      # @!method ircbot(options = {})
+      # Specify an `ircbot` component for a job.
+      #
+      # See {http://ci.openstack.org/jenkins-job-builder/publishers.html#publishers.ircbot}.
+      #
+      # @param options [Hash] The configuration options for the component.
+      # @return [Hash] The specification for the component.
+      standard_component :ircbot
 
-      # Define an `xunit` component for a job.
+      # @!method junit(options = {})
+      # Specify a `junit` component for a job.
+      #
+      # See {http://ci.openstack.org/jenkins-job-builder/publishers.html#publishers.junit}.
+      #
+      # @param options [Hash] The configuration options for the component.
+      # @return [Hash] The specification for the component.
+      standard_component :junit
+
+      # @!method trigger(options = {})
+      # Specify a `trigger` component for a job.
+      #
+      # See {http://ci.openstack.org/jenkins-job-builder/publishers.html#publishers.trigger}.
+      #
+      # @param options [Hash] The configuration options for the component.
+      # @return [Hash] The specification for the component.
+      standard_component :trigger
+
+      # Specify an `xunit` component for a job.
       #
       # See {http://ci.openstack.org/jenkins-job-builder/publishers.html#publishers.xunit}.
       #
@@ -24,14 +76,20 @@ module Publishers
       # @param options [Hash] Top-level options for configuring the component.
       # @yieldparam types [Array] An array to which nested test type specifications should be
       #   added by the block.
+      # @return [Hash] The specification for the component.
       def xunit(options = {}, &block)
         to_config("xunit", nested_options(:types, options, &block))
       end
 
-      # @!endgroup
-
       # @!group xunit Test Types
 
+      # @!method unittest(options = {})
+      # Configure a `unittest` test type for an {#xunit} component.
+      #
+      # See {http://ci.openstack.org/jenkins-job-builder/publishers.html#publishers.xunit}.
+      #
+      # @param options [Hash] The configuration options for the test type.
+      # @return [Hash] The specification for the test type.
       named_config :unittest
 
     end

lib/jujube/components/scm.rb

@@ -5,6 +5,13 @@ module Components
     module Scm
       extend Macros
 
+      # @!method git(options = {})
+      # Specify a `git` component for a job.
+      #
+      # See {http://ci.openstack.org/jenkins-job-builder/publishers.html#scm.git}.
+      #
+      # @param options [Hash] The configuration options for the component.
+      # @return [Hash] The specification for the component.
       standard_component :git
 
     end

lib/jujube/components/triggers.rb

@@ -4,16 +4,17 @@ module Components
     # Helper methods for creating trigger components.
     module Triggers
 
-      # Define a `pollscm` trigger for a job.
+      # Specify a `pollscm` trigger for a job.
       #
       # See {http://ci.openstack.org/jenkins-job-builder/triggers.html#triggers.pollscm}.
       #
       # @param interval [String] The polling interval, using `cron` syntax.
+      # @return [Hash] The specification for the component.
       def pollscm(interval)
         {'pollscm' => interval}
       end
 
-      # Define a `pollurl` trigger for a job.
+      # Specify a `pollurl` trigger for a job.
       #
       # This trigger requires support in jenkins-job-builder that has not yet been merged.
       # See {https://review.openstack.org/#/c/83524/} for the patch.
@@ -33,6 +34,7 @@ def pollscm(interval)
       # @param options [Hash] Top-level options for configuring the component.
       # @yieldparam urls [Array] An array to which nested URL specifications should be
       #   added by the block.
+      # @return [Hash] The specification for the component.
       def pollurl(options = {}, &block)
         to_config("pollurl", nested_options(:urls, options, &block))
       end
@@ -49,6 +51,7 @@ def pollurl(options = {}, &block)
       # @param options [Hash] Top-level options for this URL.
       # @yieldparam content_types [Array] An array to which nested content-type
       #   specifications should be added by the block.
+      # @return [Hash] The specification for the URL.
       def url(the_url, options = {}, &block)
         options = {url: the_url}.merge!(options)
         canonicalize_options(nested_options(:check_content, options, &block))
@@ -60,6 +63,7 @@ def url(the_url, options = {}, &block)
 
       # Configure a simple content check inside a {#url} specification of a
       # {#pollurl} component.
+      # @return [Hash] The specification for the content type.
       def simple
         {"simple" => true}
       end
@@ -69,6 +73,7 @@ def simple
       #
       # @param paths [String...] Zero or more JSONPath expressions.  Only changes to
       #   the parts of the JSON response that match one of the `paths` will trigger a build.
+      # @return [Hash] The specification for the content type.
       def json(*paths)
         {"json" => paths}
       end
@@ -78,6 +83,7 @@ def json(*paths)
       #
       # @param xpaths [String...] Zero or more XPath expressions.  Only changes to
       #   the parts of the XML response that match one of the `xpaths` will trigger a build.
+      # @return [Hash] The specification for the content type.
       def xml(*xpaths)
         {"xml" => xpaths}
       end
@@ -87,6 +93,7 @@ def xml(*xpaths)
       #
       # @param regexes [String...] Zero or more regular expressions.  Only changes to
       #   the parts of the text response that match one of the `regexes` will trigger a build.
+      # @return [Hash] The specification for the content type.
       def text(*regexes)
         {"text" => regexes}
       end

lib/jujube/components/wrappers.rb

@@ -5,11 +5,20 @@ module Components
     module Wrappers
       extend Macros
 
+      # @!method timeout(options = {})
+      # Specify a `timeout` component for a job.
+      #
+      # See {http://ci.openstack.org/jenkins-job-builder/publishers.html#wrappers.timeout}.
+      #
+      # @param options [Hash] The configuration options for the component.
+      # @return [Hash] The specification for the component.
       standard_component :timeout
 
-      # Define a `timestamps` component for a job.
+      # Specify a `timestamps` component for a job.
       #
       # See {http://ci.openstack.org/jenkins-job-builder/wrappers.html#wrappers.timestamps}.
+      #
+      # @return [Hash] The specification for the component.
       def timestamps
         'timestamps'
       end

lib/jujube/macros.rb

@@ -1,4 +1,5 @@
 module Jujube
+
   # Macros for defining methods that make it easier to specify the parts
   # a job.
   module Macros