Skip to content

Commit 342783c

Browse files
committed
Document the remaining components
1 parent 4f8a020 commit 342783c

File tree

8 files changed

+108
-22
lines changed

8 files changed

+108
-22
lines changed

lib/jujube/components/builders.rb

+2-1
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,12 @@ module Components
44
# Helper methods for creating builder components.
55
module Builders
66

7-
# Define a `shell` builder for a job.
7+
# Specify a `shell` builder for a job.
88
#
99
# See {http://ci.openstack.org/jenkins-job-builder/builders.html#builders.shell}.
1010
#
1111
# @param command [String] The shell command to execute.
12+
# @return [Hash] The specification for the component.
1213
def shell(command)
1314
{'shell' => command}
1415
end

lib/jujube/components/macros.rb

+11-11
Original file line numberDiff line numberDiff line change
@@ -5,25 +5,25 @@ module Components
55
module Macros
66
include Jujube::Utils
77

8-
# A macro that defines methods that generate a standard component. A standard
9-
# component has a name and a `Hash` of named options. The names and all option
8+
private
9+
10+
# A macro that defines a standard component. A standard
11+
# component has a name and a `Hash` of named options. The name and all option
1012
# keys are {#canonicalize}d.
1113
#
12-
# @param names [Array<Symbol>] The names of the methods to generate.
13-
def standard_component(*names)
14-
named_config(*names)
14+
# @param name [Symbol] The name of the component to generate.
15+
def standard_component(name)
16+
named_config(name)
1517
end
1618

1719
# A macro that defines methods that generate a standard named
1820
# configuration. A standard named configuration has a name and a `Hash`
1921
# of named options. The names and all option keys are {#canonicalize}d.
2022
#
21-
# @param names [Array<Symbol>] Symbols naming the methods to generate.
22-
def named_config(*names)
23-
names.each do |name|
24-
define_method(name) do |options = {}|
25-
to_config(canonicalize(name), options)
26-
end
23+
# @param name [Symbol] The name of the method to generate.
24+
def named_config(name)
25+
define_method(name) do |options = {}|
26+
to_config(canonicalize(name), options)
2727
end
2828
end
2929
end

lib/jujube/components/parameters.rb

+6-3
Original file line numberDiff line numberDiff line change
@@ -6,35 +6,38 @@ module Parameters
66

77
# @!group Matrix Axes
88

9-
# Define a `label-expression` axis for a matrix job.
9+
# Specify a `label-expression` axis for a matrix job.
1010
#
1111
# See {http://ci.openstack.org/jenkins-job-builder/project_matrix.html}.
1212
#
1313
# @param name [Symbol, String] The name of the axis.
1414
# @param values [Array<String>] The values of the axis.
15+
# @return [Hash] The specification for the axis.
1516
def label_expression(name, values)
1617
axis(name, values, :label_expression)
1718
end
1819

19-
# Define a `slave` axis for a matrix job.
20+
# Specify a `slave` axis for a matrix job.
2021
#
2122
# See {http://ci.openstack.org/jenkins-job-builder/project_matrix.html}.
2223
#
2324
# @param name [Symbol, String] The name of the axis.
2425
# @param values [Array<String>] The values of the axis.
26+
# @return [Hash] The specification for the axis.
2527
def slave(name, values)
2628
axis(name, values, :slave)
2729
end
2830

2931
private
3032

31-
# Define an axis for a matrix job.
33+
# Specify an axis for a matrix job.
3234
#
3335
# See {http://ci.openstack.org/jenkins-job-builder/project_matrix.html}.
3436
#
3537
# @param name [Symbol, String] The name of the axis.
3638
# @param values [Array<String>] The values of the axis.
3739
# @param type [Symbol, String] The axis type.
40+
# @return [Hash] The specification for the axis.
3841
def axis(name, values, type)
3942
options = {type: canonicalize(type), name: canonicalize(name), values: values}
4043
to_config("axis", options)

lib/jujube/components/publishers.rb

+62-4
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,61 @@ module Components
55
module Publishers
66
extend Macros
77

8-
standard_component :archive, :cppcheck, :email_ext, :ircbot, :junit, :trigger
8+
# @!method archive(options = {})
9+
# Specify an `archive` component for a job.
10+
#
11+
# See {http://ci.openstack.org/jenkins-job-builder/publishers.html#publishers.archive}.
12+
#
13+
# @param options [Hash] The configuration options for the component.
14+
# @return [Hash] The specification for the component.
15+
standard_component :archive
16+
17+
# @!method cppcheck(options = {})
18+
# Specify a `cppcheck` component for a job.
19+
#
20+
# See {http://ci.openstack.org/jenkins-job-builder/publishers.html#publishers.cppcheck}.
21+
#
22+
# @param options [Hash] The configuration options for the component.
23+
# @return [Hash] The specification for the component.
24+
standard_component :cppcheck
25+
26+
# @!method email_ext(options = {})
27+
# Specify an `email-ext` component for a job.
28+
#
29+
# See {http://ci.openstack.org/jenkins-job-builder/publishers.html#publishers.email-ext}.
30+
#
31+
# @param options [Hash] The configuration options for the component.
32+
# @return [Hash] The specification for the component.
33+
standard_component :email_ext
34+
35+
# @!method ircbot(options = {})
36+
# Specify an `ircbot` component for a job.
37+
#
38+
# See {http://ci.openstack.org/jenkins-job-builder/publishers.html#publishers.ircbot}.
39+
#
40+
# @param options [Hash] The configuration options for the component.
41+
# @return [Hash] The specification for the component.
42+
standard_component :ircbot
943

10-
# Define an `xunit` component for a job.
44+
# @!method junit(options = {})
45+
# Specify a `junit` component for a job.
46+
#
47+
# See {http://ci.openstack.org/jenkins-job-builder/publishers.html#publishers.junit}.
48+
#
49+
# @param options [Hash] The configuration options for the component.
50+
# @return [Hash] The specification for the component.
51+
standard_component :junit
52+
53+
# @!method trigger(options = {})
54+
# Specify a `trigger` component for a job.
55+
#
56+
# See {http://ci.openstack.org/jenkins-job-builder/publishers.html#publishers.trigger}.
57+
#
58+
# @param options [Hash] The configuration options for the component.
59+
# @return [Hash] The specification for the component.
60+
standard_component :trigger
61+
62+
# Specify an `xunit` component for a job.
1163
#
1264
# See {http://ci.openstack.org/jenkins-job-builder/publishers.html#publishers.xunit}.
1365
#
@@ -24,14 +76,20 @@ module Publishers
2476
# @param options [Hash] Top-level options for configuring the component.
2577
# @yieldparam types [Array] An array to which nested test type specifications should be
2678
# added by the block.
79+
# @return [Hash] The specification for the component.
2780
def xunit(options = {}, &block)
2881
to_config("xunit", nested_options(:types, options, &block))
2982
end
3083

31-
# @!endgroup
32-
3384
# @!group xunit Test Types
3485

86+
# @!method unittest(options = {})
87+
# Configure a `unittest` test type for an {#xunit} component.
88+
#
89+
# See {http://ci.openstack.org/jenkins-job-builder/publishers.html#publishers.xunit}.
90+
#
91+
# @param options [Hash] The configuration options for the test type.
92+
# @return [Hash] The specification for the test type.
3593
named_config :unittest
3694

3795
end

lib/jujube/components/scm.rb

+7
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,13 @@ module Components
55
module Scm
66
extend Macros
77

8+
# @!method git(options = {})
9+
# Specify a `git` component for a job.
10+
#
11+
# See {http://ci.openstack.org/jenkins-job-builder/publishers.html#scm.git}.
12+
#
13+
# @param options [Hash] The configuration options for the component.
14+
# @return [Hash] The specification for the component.
815
standard_component :git
916

1017
end

lib/jujube/components/triggers.rb

+9-2
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,17 @@ module Components
44
# Helper methods for creating trigger components.
55
module Triggers
66

7-
# Define a `pollscm` trigger for a job.
7+
# Specify a `pollscm` trigger for a job.
88
#
99
# See {http://ci.openstack.org/jenkins-job-builder/triggers.html#triggers.pollscm}.
1010
#
1111
# @param interval [String] The polling interval, using `cron` syntax.
12+
# @return [Hash] The specification for the component.
1213
def pollscm(interval)
1314
{'pollscm' => interval}
1415
end
1516

16-
# Define a `pollurl` trigger for a job.
17+
# Specify a `pollurl` trigger for a job.
1718
#
1819
# This trigger requires support in jenkins-job-builder that has not yet been merged.
1920
# See {https://review.openstack.org/#/c/83524/} for the patch.
@@ -33,6 +34,7 @@ def pollscm(interval)
3334
# @param options [Hash] Top-level options for configuring the component.
3435
# @yieldparam urls [Array] An array to which nested URL specifications should be
3536
# added by the block.
37+
# @return [Hash] The specification for the component.
3638
def pollurl(options = {}, &block)
3739
to_config("pollurl", nested_options(:urls, options, &block))
3840
end
@@ -49,6 +51,7 @@ def pollurl(options = {}, &block)
4951
# @param options [Hash] Top-level options for this URL.
5052
# @yieldparam content_types [Array] An array to which nested content-type
5153
# specifications should be added by the block.
54+
# @return [Hash] The specification for the URL.
5255
def url(the_url, options = {}, &block)
5356
options = {url: the_url}.merge!(options)
5457
canonicalize_options(nested_options(:check_content, options, &block))
@@ -60,6 +63,7 @@ def url(the_url, options = {}, &block)
6063

6164
# Configure a simple content check inside a {#url} specification of a
6265
# {#pollurl} component.
66+
# @return [Hash] The specification for the content type.
6367
def simple
6468
{"simple" => true}
6569
end
@@ -69,6 +73,7 @@ def simple
6973
#
7074
# @param paths [String...] Zero or more JSONPath expressions. Only changes to
7175
# the parts of the JSON response that match one of the `paths` will trigger a build.
76+
# @return [Hash] The specification for the content type.
7277
def json(*paths)
7378
{"json" => paths}
7479
end
@@ -78,6 +83,7 @@ def json(*paths)
7883
#
7984
# @param xpaths [String...] Zero or more XPath expressions. Only changes to
8085
# the parts of the XML response that match one of the `xpaths` will trigger a build.
86+
# @return [Hash] The specification for the content type.
8187
def xml(*xpaths)
8288
{"xml" => xpaths}
8389
end
@@ -87,6 +93,7 @@ def xml(*xpaths)
8793
#
8894
# @param regexes [String...] Zero or more regular expressions. Only changes to
8995
# the parts of the text response that match one of the `regexes` will trigger a build.
96+
# @return [Hash] The specification for the content type.
9097
def text(*regexes)
9198
{"text" => regexes}
9299
end

lib/jujube/components/wrappers.rb

+10-1
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,20 @@ module Components
55
module Wrappers
66
extend Macros
77

8+
# @!method timeout(options = {})
9+
# Specify a `timeout` component for a job.
10+
#
11+
# See {http://ci.openstack.org/jenkins-job-builder/publishers.html#wrappers.timeout}.
12+
#
13+
# @param options [Hash] The configuration options for the component.
14+
# @return [Hash] The specification for the component.
815
standard_component :timeout
916

10-
# Define a `timestamps` component for a job.
17+
# Specify a `timestamps` component for a job.
1118
#
1219
# See {http://ci.openstack.org/jenkins-job-builder/wrappers.html#wrappers.timestamps}.
20+
#
21+
# @return [Hash] The specification for the component.
1322
def timestamps
1423
'timestamps'
1524
end

lib/jujube/macros.rb

+1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
module Jujube
2+
23
# Macros for defining methods that make it easier to specify the parts
34
# a job.
45
module Macros

0 commit comments

Comments
 (0)