Skip to content

Commit 2e9de3c

Browse files
juniper-shopifyjuniper-shopify
committed
Add method doc to cogs config
Part of a gradual process to add comprehensive documentation comments to all user-facing interfaces before the v1.0 release
1 parent 7ba9e24 commit 2e9de3c

File tree

2 files changed

+149
-17
lines changed

2 files changed

+149
-17
lines changed

‎lib/roast/dsl/cog.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ def run!(config, input_context, executor_scope_value, executor_scope_index)
8181
@failed = true
8282
# TODO: better / cleaner handling in the workflow execution manager for a workflow failure
8383
# just re-raising this exception for now
84-
raise e if config.exit_on_error?
84+
raise e if config.abort_on_error?
8585
end
8686
end
8787

‎lib/roast/dsl/cog/config.rb‎

Lines changed: 148 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -29,20 +29,65 @@ def merge(config_object)
2929
self.class.new(values.merge(config_object.values))
3030
end
3131

32-
# It is recommended to implement a custom config object for a nicer interface,
33-
# but for simple cases where it would just be a key value store we provide one by default.
34-
32+
# Set a configuration value using hash-style syntax
33+
#
34+
# This method provides basic key-value storage for cog configuration.
35+
# All standard Roast cogs use imperative setter methods for config values.
36+
# It is recommended that custom cogs implement their own config classes with similar methods
37+
# for a more structured interface, but this hash-style syntax is provided for simple cases.
38+
#
39+
# #### See Also
40+
# - `[]`
41+
#
3542
#: (Symbol, untyped) -> void
3643
def []=(key, value)
3744
@values[key] = value
3845
end
3946

47+
# Get a configuration value using hash-style syntax
48+
#
49+
# This method provides basic key-value retrieval for cog configuration.
50+
# All standard Roast cogs use imperative setter methods for config values.
51+
# It is recommended that custom cogs implement their own config classes with similar methods
52+
# for a more structured interface, but this hash-style syntax is provided for simple cases.
53+
#
54+
# #### See Also
55+
# - `[]=`
56+
#
4057
#: (Symbol) -> untyped
4158
def [](key)
4259
@values[key]
4360
end
4461

4562
class << self
63+
# Define a configuration field with simple, out-of-the-box getter/setter behavior
64+
# and default value handling
65+
#
66+
# #### Generated Methods
67+
# This method creates two methods for a configuration field:
68+
# 1. A dual-purpose method (`key`) that gets the value when called without arguments,
69+
# or sets the value when called with an argument.
70+
# 2. A bang method (`use_default_#{key}!`) that explicitly resets the field to its default value.
71+
#
72+
# When getting a value without arguments, the configured value is returned if set,
73+
# otherwise the default value is returned.
74+
# When setting a value with an argument, the validator block is applied if provided.
75+
#
76+
# #### Validation
77+
#
78+
# This method accepts an optional `validator` block that will be called with the new value
79+
# when the field's setter method is invoked. The validator should raise an exception if the
80+
# provided value is not valid. It's return value will be used as the new config value.
81+
# This allows the validator to coerce an value into a standard form if desired.
82+
#
83+
# ##### See Also
84+
# - `Cog::Config#validate!` - validates the config object as a whole, after all values have been set
85+
#
86+
# #### Parameters
87+
# - `key` - The name of the configuration field
88+
# - `default` - The default value for this field
89+
# - `validator` - Optional block that validates and/or transforms the value before storing it
90+
#
4691
#: [T] (Symbol, T) ?{(T) -> T} -> void
4792
def field(key, default, &validator)
4893
default = default #: as untyped
@@ -65,37 +110,124 @@ def field(key, default, &validator)
65110
end
66111
end
67112

113+
# Configure the cog to run asynchronously in the background
114+
#
115+
# When configured to run asynchronously, the cog will execute in the background
116+
# and the next cog in the workflow will be able to start immediately without waiting
117+
# for this cog to complete.
118+
#
119+
# If this cog has started running, attempts to access its output from another cog will
120+
# block until this cog completes.
121+
# If this cog has not yet started, attempts to access its output from another cog will
122+
# fail in the same way that accessing the output of a synchronous cog that has not yet
123+
# run would fail.
124+
#
125+
# The workflow will not complete until all asynchronous cogs have completed (or failed).
126+
#
127+
# #### Inverse Methods
128+
# - `no_async!`
129+
# - `sync!`
130+
#
131+
# #### See Also
132+
# - `async?`
133+
#
68134
#: () -> void
69-
def exit_on_error!
70-
@values[:exit_on_error] = true
135+
def async!
136+
@values[:async] = true
71137
end
72138

139+
# Configure the cog __not__ to run asynchronously
140+
#
141+
# When configured not to run asynchronously, the cog will execute synchronously
142+
# and the next cog in the workflow will wait for this cog to complete before starting.
143+
#
144+
# #### Alias Methods
145+
# - `no_async!`
146+
# - `sync!`
147+
#
148+
# #### Inverse Methods
149+
# - `async!`
150+
#
151+
# #### See Also
152+
# - `async?`
153+
#
73154
#: () -> void
74-
def no_exit_on_error!
75-
@values[:exit_on_error] = false
155+
def no_async!
156+
@values[:async] = false
76157
end
77158

159+
# Check if the cog is configured to run asynchronously
160+
#
161+
# #### See Also
162+
# - `async!`
163+
# - `no_async!`
164+
# - `sync!`
165+
#
78166
#: () -> bool
79-
def exit_on_error?
80-
@values[:exit_on_error] ||= true
167+
def async?
168+
!!@values[:async]
81169
end
82170

171+
# Configure the cog to abort the workflow immediately if it fails to complete successfully
172+
#
173+
# Enabled by default.
174+
#
175+
# #### Alias Methods
176+
# - `abort_on_error!`
177+
# - `exit_on_error!`
178+
#
179+
# #### Inverse Methods
180+
# - `continue_on_error!`
181+
# - `no_abort_on_error!`
182+
# - `no_exit_on_error!`
183+
#
184+
# #### See Also
185+
# - `abort_on_error?`
186+
#
83187
#: () -> void
84-
def async!
85-
@values[:async] = true
188+
def abort_on_error!
189+
@values[:exit_on_error] = true
86190
end
87191

192+
# Configure the cog __not__ to abort the workflow if it fails to complete successfully
193+
#
194+
# When a cog is configured not to abort on error, the workflow will continue to run subsequent cogs
195+
# even if that cog fails. However, attempts to access that cog's output from another cog will fail.
196+
#
197+
# #### Alias Methods
198+
# - `continue_on_error!`
199+
# - `no_abort_on_error!`
200+
# - `no_exit_on_error!`
201+
#
202+
# #### Inverse Methods
203+
# - `abort_on_error!`
204+
# - `exit_on_error!`
205+
#
206+
# #### See Also
207+
# - `abort_on_error?`
208+
#
88209
#: () -> void
89-
def no_async!
90-
@values[:async] = false
210+
def no_abort_on_error!
211+
@values[:exit_on_error] = false
91212
end
92213

214+
# Check if the cog is configured to abort the workflow immediately on error
215+
#
216+
# #### See Also
217+
# - `abort_on_error!`
218+
# - `continue_on_error!`
219+
# - `exit_on_error!`
220+
# - `no_abort_on_error!`
221+
# - `no_exit_on_error!`
222+
#
93223
#: () -> bool
94-
def async?
95-
!!@values[:async]
224+
def abort_on_error?
225+
@values[:exit_on_error] ||= true
96226
end
97227

98-
alias_method(:continue_on_error!, :no_exit_on_error!)
228+
alias_method(:exit_on_error!, :abort_on_error!)
229+
alias_method(:no_exit_on_error!, :no_abort_on_error!)
230+
alias_method(:continue_on_error!, :no_abort_on_error!)
99231
alias_method(:sync!, :no_async!)
100232
end
101233
end

0 commit comments

Comments
 (0)