state_machines-yard 0.0.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. checksums.yaml +5 -5
  2. data/.github/workflows/ci.yml +32 -0
  3. data/.github/workflows/release.yml +18 -0
  4. data/.release-please-manifest.json +3 -0
  5. data/.rubocop.yml +38 -0
  6. data/CHANGELOG.md +44 -0
  7. data/Gemfile +13 -0
  8. data/LICENSE.txt +1 -1
  9. data/README.md +50 -1
  10. data/Rakefile +29 -0
  11. data/lib/state_machines/yard/description.rb +74 -0
  12. data/lib/state_machines/yard/handlers/base.rb +122 -21
  13. data/lib/state_machines/yard/handlers/callback.rb +96 -0
  14. data/lib/state_machines/yard/handlers/event.rb +20 -11
  15. data/lib/state_machines/yard/handlers/machine.rb +263 -241
  16. data/lib/state_machines/yard/handlers/requirements.rb +92 -0
  17. data/lib/state_machines/yard/handlers/state.rb +20 -11
  18. data/lib/state_machines/yard/handlers/transition.rb +26 -31
  19. data/lib/state_machines/yard/handlers.rb +4 -6
  20. data/lib/state_machines/yard/renderer.rb +62 -0
  21. data/lib/state_machines/yard/templates/default/class/html/setup.rb +14 -7
  22. data/lib/state_machines/yard/templates/default/class/html/state_machines.erb +33 -0
  23. data/lib/state_machines/yard/templates.rb +2 -0
  24. data/lib/state_machines/yard/version.rb +3 -1
  25. data/lib/state_machines/yard.rb +15 -4
  26. data/release-please-config.json +11 -0
  27. data/state_machines-yard.gemspec +19 -11
  28. data/test/description_test.rb +99 -0
  29. data/test/handlers/base_test.rb +83 -0
  30. data/test/handlers/callback_test.rb +137 -0
  31. data/test/handlers/event_test.rb +97 -0
  32. data/test/handlers/guards_test.rb +180 -0
  33. data/test/handlers/machine_test.rb +156 -0
  34. data/test/handlers/review_test.rb +192 -0
  35. data/test/handlers/state_test.rb +73 -0
  36. data/test/handlers/transition_test.rb +142 -0
  37. data/test/integration_test.rb +163 -0
  38. data/test/templates_test.rb +95 -0
  39. data/test/test_helper.rb +51 -0
  40. metadata +146 -16
@@ -1,80 +1,137 @@
1
- module StateMachine
2
- module YARD
1
+ # frozen_string_literal: true
2
+
3
+ require_relative '../renderer'
4
+
5
+ module StateMachines
6
+ module Yard
3
7
  module Handlers
4
8
  # Handles and processes #state_machine
5
9
  class Machine < Base
6
10
  handles method_call(:state_machine)
7
11
  namespace_only
8
12
 
13
+ # Store the handled method name for testing
14
+ @handles_method = :state_machine
15
+
16
+ # What a renderer adds to a machine's entry
17
+ DIAGRAM_KEYS = %i[image mermaid renderer].freeze
18
+
19
+ # Stands for an initial state the documented code computes
20
+ DYNAMIC_INITIAL_STATE = ->(_object) {}
21
+
9
22
  # The generated state machine
10
23
  attr_reader :machine
11
24
 
12
25
  def process
13
- # Cross-file storage for state machines
14
- globals.state_machines ||= Hash.new { |h, k| h[k] = {} }
15
- namespace['state_machines'] ||= {}
16
-
17
- # Create new machine
18
- klass = inherited_machine ? Class.new(inherited_machine.owner_class) : Class.new { extend StateMachines::MacroMethods }
19
- @machine = klass.state_machine(name, options) {}
26
+ name # A machine whose name is code is not documented
27
+
28
+ # A machine the class already documents is reopened, as the core
29
+ # does. Given a block, even an empty one, the core copies an
30
+ # inherited machine for the subclass instead of extending the
31
+ # superclass's, and applies the subclass's options to the copy.
32
+ @machine = (reopened_machine&.owner_class || owner_class).state_machine(name, options) do
33
+ # The statement's block is parsed below
34
+ end
20
35
 
21
- # Track the state machine
22
- globals.state_machines[namespace.name][name] = machine
23
- namespace['state_machines'][name] = {name: name, description: statement.docstring}
36
+ track_machine
24
37
 
25
38
  # Parse the block
26
- parse_block(statement.last.last, owner: machine)
39
+ parse_block(statement.block.last, owner: machine) if statement.block
27
40
 
28
- # Draw the machine for reference in the template
29
- file = Tempfile.new(['state_machine', '.png'])
30
- begin
31
- if machine.draw(name: File.basename(file.path, '.png'), path: File.dirname(file.path), orientation: 'landscape')
32
- namespace['state_machines'][name][:image] = file.read
33
- end
34
- ensure
35
- # Clean up tempfile
36
- file.close
37
- file.unlink
38
- end
41
+ document_events
42
+ document_diagram
39
43
 
40
44
  # Define auto-generated methods
41
45
  define_macro_methods
42
46
  define_state_methods
43
47
  define_event_methods
48
+ rescue Unreadable, ArgumentError => e
49
+ # A machine the core refuses (an option a reopened machine cannot
50
+ # change) is not documented as something else
51
+ skip('state machine', e)
44
52
  end
45
53
 
46
54
  protected
47
- # Extracts the machine name's
55
+
56
+ # The class the documented machine is built on: a subclass of the
57
+ # inherited machine's owner, so the machine extends that one. It is
58
+ # named as the documented class, which diagrams show in their title.
59
+ def owner_class
60
+ klass = inherited_machine ? Class.new(inherited_machine.owner_class) : Class.new { extend MacroMethods }
61
+ path = namespace.path
62
+ klass.define_singleton_method(:name) { path }
63
+ klass.define_singleton_method(:to_s) { path }
64
+ klass
65
+ end
66
+
67
+ # The machine this class already documents under the name, if any
68
+ def reopened_machine
69
+ globals.state_machines&.dig(namespace.path, name)
70
+ end
71
+
72
+ # Stores the machine across files (subclasses find it there) and on
73
+ # the documented class
74
+ def track_machine
75
+ globals.state_machines ||= Hash.new { |h, k| h[k] = {} }
76
+ globals.state_machines[namespace.path][name] = machine
77
+ namespace['state_machines'] ||= {}
78
+ entry = namespace['state_machines'][name] ||= { name: name }
79
+ entry[:description] = statement.docstring unless statement.docstring.to_s.empty? && entry[:description]
80
+ end
81
+
82
+ # The events' transitions, guards and callbacks as text, whatever
83
+ # renderer draws the diagram
84
+ def document_events
85
+ @events = Description.events(machine).to_h { [it[:name], it] }
86
+ namespace['state_machines'][name][:events] = @events.values
87
+ end
88
+
89
+ # The machine's diagram, drawn by the selected renderer
90
+ # A reopened machine is drawn again: its previous diagram shows only
91
+ # what was declared before, so it is never kept in place of a new one
92
+ def document_diagram
93
+ entry = namespace['state_machines'][name]
94
+ stale = entry.slice(*DIAGRAM_KEYS)
95
+ DIAGRAM_KEYS.each { entry.delete(it) }
96
+ render = Renderer.render(machine)
97
+ return entry.merge!(render, renderer: Renderer.selection) if render
98
+
99
+ warn_stale_diagram unless stale.except(:renderer).empty?
100
+ end
101
+
102
+ def warn_stale_diagram
103
+ log.warn "state_machines-yard: the reopened #{name} machine could not be drawn again; " \
104
+ "its earlier diagram is left out (#{parser.file}:#{statement.line})"
105
+ end
106
+
107
+ # The machine's name: its first argument, :state when there is none
48
108
  def name
49
109
  @name ||= begin
50
- ast = statement.parameters.first
51
- if ast && [:symbol_literal, :string_literal].include?(ast.type)
52
- extract_node_name(ast)
53
- else
54
- :state
55
- end
110
+ argument = positional_arguments.first
111
+ argument ? name_literal(argument) : :state
56
112
  end
57
113
  end
58
114
 
59
- # Extracts the machine options. Note that this will only extract a
60
- # subset of the options supported.
115
+ # The machine options documentation depends on. Note that this will
116
+ # only extract a subset of the options supported. An initial state
117
+ # written as code is decided when the object is created, so no state
118
+ # is documented as the initial one.
61
119
  def options
62
120
  @options ||= begin
63
- options = {}
64
- ast = statement.parameters(false).last
65
-
66
- if !inherited_machine && ast && ![:symbol_literal, :string_literal].include?(ast.type)
67
- ast.children.each do |assoc|
68
- # Only extract important options
69
- key = extract_node_name(assoc[0])
70
- next unless [:initial, :attribute, :namespace, :action].include?(key)
121
+ options = literal_options(%i[initial attribute namespace action])
122
+ options[:initial] = DYNAMIC_INITIAL_STATE if dynamic_initial_state?
123
+ options
124
+ end
125
+ end
71
126
 
72
- value = extract_node_name(assoc[1])
73
- options[key] = value
74
- end
127
+ def dynamic_initial_state?
128
+ option_pairs.any? do |key, value|
129
+ literal(key) == :initial && begin
130
+ literal(value)
131
+ false
132
+ rescue Unreadable
133
+ true
75
134
  end
76
-
77
- options
78
135
  end
79
136
  end
80
137
 
@@ -83,17 +140,15 @@ module StateMachine
83
140
  def inherited_machine
84
141
  @inherited_machine ||= begin
85
142
  namespace.inheritance_tree.each do |ancestor|
86
- begin
87
- ensure_loaded!(ancestor)
88
- rescue ::YARD::Handlers::NamespaceMissingError
89
- # Ignore: just means that we can't access an ancestor
90
- end
143
+ ensure_loaded!(ancestor)
144
+ rescue YARD::Handlers::NamespaceMissingError
145
+ # Ignore: just means that we can't access an ancestor
91
146
  end
92
147
 
93
148
  # Find the first ancestor that has the machine
94
149
  loaded_superclasses.find do |superclass|
95
150
  if superclass != namespace
96
- machine = globals.state_machines[superclass.name][name]
151
+ machine = globals.state_machines[superclass.path][name]
97
152
  break machine if machine
98
153
  end
99
154
  end
@@ -103,7 +158,7 @@ module StateMachine
103
158
  # Gets members of this class's superclasses have already been loaded
104
159
  # by YARD
105
160
  def loaded_superclasses
106
- namespace.inheritance_tree.select { |ancestor| ancestor.is_a?(::YARD::CodeObjects::ClassObject) }
161
+ namespace.inheritance_tree.grep(YARD::CodeObjects::ClassObject)
107
162
  end
108
163
 
109
164
  # Gets a list of all attributes for the current class, including those
@@ -117,12 +172,16 @@ module StateMachine
117
172
  # Gets the type of ORM integration being used based on the list of
118
173
  # ancestors (including mixins)
119
174
  def integration
120
- @integration ||= Integrations.match_ancestors(namespace.inheritance_tree(true).map { |ancestor| ancestor.path })
175
+ @integration ||= Integrations.match_ancestors(namespace.inheritance_tree(true).map(&:path))
121
176
  end
122
177
 
123
178
  # Gets the class type being used to define states. Default is "Symbol".
124
179
  def state_type
125
- @state_type ||= machine.states.any? ? machine.states.map { |state| state.name }.compact.first.class.to_s : 'Symbol'
180
+ @state_type ||= if machine.states.any?
181
+ machine.states.filter_map(&:name).first.class.to_s
182
+ else
183
+ 'Symbol'
184
+ end
126
185
  end
127
186
 
128
187
  # Gets the class type being used to define events. Default is "Symbol".
@@ -130,210 +189,173 @@ module StateMachine
130
189
  @event_type ||= machine.events.any? ? machine.events.first.name.class.to_s : 'Symbol'
131
190
  end
132
191
 
133
- # Defines auto-generated macro methods for the given machine
192
+ # Registers a method the machine generates, with its documentation
193
+ def document_method(name, docstring, parameters: nil, scope: :instance)
194
+ method = YARD::CodeObjects::MethodObject.new(namespace, name, scope)
195
+ register(method)
196
+ # YARD checks @param tags against the parameters, as [name, default]
197
+ # pairs, when the docstring is set
198
+ method.parameters = parameters.map { |name, default| [name, default] } if parameters
199
+ method.docstring = docstring
200
+ method
201
+ end
202
+
203
+ # Registers an attribute's reader and writer
204
+ def document_attribute(attribute, description)
205
+ namespace.attributes[:instance][attribute] = {
206
+ read: document_method(attribute, ["Gets the current #{description} for the machine",
207
+ "@return The #{description}"]),
208
+ write: document_method("#{attribute}=", ['Sets the current value for the machine',
209
+ "@param new_#{attribute} The new value to set"],
210
+ parameters: ["new_#{attribute}"])
211
+ }
212
+ end
213
+
214
+ # Defines auto-generated macro methods for the given machine. A
215
+ # subclass's machine extends its superclass's, so the methods that
216
+ # read the current state are documented on it too; the attributes and
217
+ # the methods that list or fire events are the superclass's.
134
218
  def define_macro_methods
219
+ define_human_name_methods
220
+ define_state_reader_methods
135
221
  return if inherited_machine
136
222
 
137
- # Human state name lookup
138
- register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "human_#{machine.attribute(:name)}", :class))
139
- m.docstring = [
140
- 'Gets the humanized name for the given state.',
141
- "@param [#{state_type}] state The state to look up",
142
- '@return [String] The human state name'
143
- ]
144
- m.parameters = ['state']
145
-
146
- # Human event name lookup
147
- register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "human_#{machine.attribute(:event_name)}", :class))
148
- m.docstring = [
149
- 'Gets the humanized name for the given event.',
150
- "@param [#{event_type}] event The event to look up",
151
- '@return [String] The human event name'
152
- ]
153
- m.parameters = ['event']
154
-
155
- # Only register attributes when the accessor isn't explicitly defined
156
- # by the class / superclass *and* isn't defined by inference from the
157
- # ORM being used
223
+ define_attribute_methods
224
+ define_event_list_methods
225
+ end
226
+
227
+ def define_human_name_methods
228
+ document_method("human_#{machine.attribute(:name)}",
229
+ ['Gets the humanized name for the given state.',
230
+ "@param [#{state_type}] state The state to look up",
231
+ '@return [String] The human state name'],
232
+ parameters: ['state'], scope: :class)
233
+ document_method("human_#{machine.attribute(:event_name)}",
234
+ ['Gets the humanized name for the given event.',
235
+ "@param [#{event_type}] event The event to look up",
236
+ '@return [String] The human event name'],
237
+ parameters: ['event'], scope: :class)
238
+ end
239
+
240
+ def define_state_reader_methods
241
+ document_method("#{machine.name}?",
242
+ ['Checks the given state name against the current state.',
243
+ "@param [#{state_type}] state_name The name of the state to check",
244
+ '@return [Boolean] True if they are the same state, otherwise false',
245
+ '@raise [IndexError] If the state name is invalid'],
246
+ parameters: ['state_name'])
247
+ document_method(machine.attribute(:name),
248
+ ['Gets the internal name of the state for the current value.',
249
+ "@return [#{state_type}] The internal name of the state"])
250
+ document_method("human_#{machine.attribute(:name)}",
251
+ ['Gets the human-readable name of the state for the current value.',
252
+ '@return [String] The human-readable state name'])
253
+ end
254
+
255
+ # Only register attributes when the accessor isn't explicitly defined
256
+ # by the class / superclass *and* isn't defined by inference from the
257
+ # ORM being used
258
+ def define_attribute_methods
158
259
  unless integration || instance_attributes.include?(machine.attribute.to_sym)
159
- attribute = machine.attribute
160
- namespace.attributes[:instance][attribute] = {}
161
-
162
- # Machine attribute getter
163
- register(m = ::YARD::CodeObjects::MethodObject.new(namespace, attribute))
164
- namespace.attributes[:instance][attribute][:read] = m
165
- m.docstring = [
166
- 'Gets the current attribute value for the machine',
167
- '@return The attribute value'
168
- ]
169
-
170
- # Machine attribute setter
171
- register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "#{attribute}="))
172
- namespace.attributes[:instance][attribute][:write] = m
173
- m.docstring = [
174
- 'Sets the current value for the machine',
175
- "@param new_#{attribute} The new value to set"
176
- ]
177
- m.parameters = ["new_#{attribute}"]
260
+ document_attribute(machine.attribute, 'attribute value')
178
261
  end
262
+ document_attribute("#{machine.name}_event", 'event attribute value') if action?
263
+ end
179
264
 
180
- if integration && integration.defaults[:action] && !options.include?(:action) || options[:action]
181
- attribute = "#{machine.name}_event"
182
- namespace.attributes[:instance][attribute] = {}
183
-
184
- # Machine event attribute getter
185
- register(m = ::YARD::CodeObjects::MethodObject.new(namespace, attribute))
186
- namespace.attributes[:instance][attribute][:read] = m
187
- m.docstring = [
188
- 'Gets the current event attribute value for the machine',
189
- '@return The event attribute value'
190
- ]
191
-
192
- # Machine event attribute setter
193
- register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "#{attribute}="))
194
- namespace.attributes[:instance][attribute][:write] = m
195
- m.docstring = [
196
- 'Sets the current value for the machine',
197
- "@param new_#{attribute} The new value to set"
198
- ]
199
- m.parameters = ["new_#{attribute}"]
200
- end
265
+ # Whether the machine has an action, its own or its integration's
266
+ def action?
267
+ options.include?(:action) ? options[:action] : integration&.defaults&.[](:action)
268
+ end
269
+
270
+ def define_event_list_methods
271
+ requirements = ['@param [Hash] requirements The transition requirements to test against']
272
+ guard = '@option requirements [Boolean] :guard Whether to guard transitions with conditionals'
273
+ from_to_on = ["@option requirements [#{state_type}] :from (the current state) One or more initial states",
274
+ "@option requirements [#{state_type}] :to One or more target states",
275
+ "@option requirements [#{event_type}] :on One or more events that fire the transition"]
276
+
277
+ document_method(machine.attribute(:events),
278
+ ["Gets the list of events that can be fired on the current #{machine.name} " \
279
+ '(uses the *unqualified* event names)', *requirements, *from_to_on, guard,
280
+ "@return [Array<#{event_type}>] The list of event names"],
281
+ parameters: [%w[requirements {}]])
282
+ document_method(machine.attribute(:transitions),
283
+ ["Gets the list of transitions that can be made for the current #{machine.name}",
284
+ *requirements, *from_to_on, guard,
285
+ '@return [Array<StateMachines::Transition>] The available transitions'],
286
+ parameters: [%w[requirements {}]])
287
+ define_path_and_fire_methods(requirements, guard)
288
+ end
201
289
 
202
- # Presence query
203
- register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "#{machine.name}?"))
204
- m.docstring = [
205
- 'Checks the given state name against the current state.',
206
- "@param [#{state_type}] state_name The name of the state to check",
207
- '@return [Boolean] True if they are the same state, otherwise false',
208
- '@raise [IndexError] If the state name is invalid'
209
- ]
210
- m.parameters = ['state_name']
211
-
212
- # Internal state name
213
- register(m = ::YARD::CodeObjects::MethodObject.new(namespace, machine.attribute(:name)))
214
- m.docstring = [
215
- 'Gets the internal name of the state for the current value.',
216
- "@return [#{state_type}] The internal name of the state"
217
- ]
218
-
219
- # Human state name
220
- register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "human_#{machine.attribute(:name)}"))
221
- m.docstring = [
222
- 'Gets the human-readable name of the state for the current value.',
223
- '@return [String] The human-readable state name'
224
- ]
225
-
226
- # Available events
227
- register(m = ::YARD::CodeObjects::MethodObject.new(namespace, machine.attribute(:events)))
228
- m.docstring = [
229
- "Gets the list of events that can be fired on the current #{machine.name} (uses the *unqualified* event names)",
230
- '@param [Hash] requirements The transition requirements to test against',
231
- "@option requirements [#{state_type}] :from (the current state) One or more initial states",
232
- "@option requirements [#{state_type}] :to One or more target states",
233
- "@option requirements [#{event_type}] :on One or more events that fire the transition",
234
- '@option requirements [Boolean] :guard Whether to guard transitions with conditionals',
235
- "@return [Array<#{event_type}>] The list of event names"
236
- ]
237
- m.parameters = [['requirements', '{}']]
238
-
239
- # Available transitions
240
- register(m = ::YARD::CodeObjects::MethodObject.new(namespace, machine.attribute(:transitions)))
241
- m.docstring = [
242
- "Gets the list of transitions that can be made for the current #{machine.name}",
243
- '@param [Hash] requirements The transition requirements to test against',
244
- "@option requirements [#{state_type}] :from (the current state) One or more initial states",
245
- "@option requirements [#{state_type}] :to One or more target states",
246
- "@option requirements [#{event_type}] :on One or more events that fire the transition",
247
- '@option requirements [Boolean] :guard Whether to guard transitions with conditionals',
248
- '@return [Array<StateMachines::Transition>] The available transitions'
249
- ]
250
- m.parameters = [['requirements', '{}']]
251
-
252
- # Available transition paths
253
- register(m = ::YARD::CodeObjects::MethodObject.new(namespace, machine.attribute(:paths)))
254
- m.docstring = [
255
- "Gets the list of sequences of transitions that can be run for the current #{machine.name}",
256
- '@param [Hash] requirements The transition requirements to test against',
257
- "@option requirements [#{state_type}] :from (the current state) The initial state",
258
- "@option requirements [#{state_type}] :to The target state",
259
- '@option requirements [Boolean] :deep Whether to enable deep searches for the target state',
260
- '@option requirements [Boolean] :guard Whether to guard transitions with conditionals',
261
- '@return [StateMachines::PathCollection] The collection of paths'
262
- ]
263
- m.parameters = [['requirements', '{}']]
264
-
265
- # Generic event fire
266
- register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "fire_#{machine.attribute(:event)}"))
267
- m.docstring = [
268
- "Fires an arbitrary #{machine.name} event with the given argument list",
269
- "@param [#{event_type}] event The name of the event to fire",
270
- '@param args Optional arguments to include in the transition',
271
- '@return [Boolean] +true+ if the event succeeds, otherwise +false+'
272
- ]
273
- m.parameters = ['event', '*args']
290
+ def define_path_and_fire_methods(requirements, guard)
291
+ document_method(machine.attribute(:paths),
292
+ ["Gets the list of sequences of transitions that can be run for the current #{machine.name}",
293
+ *requirements,
294
+ "@option requirements [#{state_type}] :from (the current state) The initial state",
295
+ "@option requirements [#{state_type}] :to The target state",
296
+ '@option requirements [Boolean] :deep Whether to enable deep searches for the target state',
297
+ guard, '@return [StateMachines::PathCollection] The collection of paths'],
298
+ parameters: [%w[requirements {}]])
299
+ document_method("fire_#{machine.attribute(:event)}",
300
+ ["Fires an arbitrary #{machine.name} event with the given argument list",
301
+ "@param [#{event_type}] event The name of the event to fire",
302
+ '@param args Optional arguments to include in the transition',
303
+ '@return [Boolean] +true+ if the event succeeds, otherwise +false+'],
304
+ parameters: ['event', '*args'])
274
305
  end
275
306
 
276
307
  # Defines auto-generated event methods for the given machine
277
308
  def define_event_methods
278
309
  machine.events.each do |event|
279
- next if inherited_machine && inherited_machine.events[event.name]
280
-
281
- # Event query
282
- register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "can_#{event.qualified_name}?"))
283
- m.docstring = [
284
- "Checks whether #{event.name.inspect} can be fired.",
285
- '@param [Hash] requirements The transition requirements to test against',
286
- "@option requirements [#{state_type}] :from (the current state) One or more initial states",
287
- "@option requirements [#{state_type}] :to One or more target states",
288
- '@option requirements [Boolean] :guard Whether to guard transitions with conditionals',
289
- "@return [Boolean] +true+ if #{event.name.inspect} can be fired, otherwise +false+"
290
- ]
291
- m.parameters = [['requirements', '{}']]
292
-
293
- # Event transition
294
- register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "#{event.qualified_name}_transition"))
295
- m.docstring = [
296
- "Gets the next transition that would be performed if #{event.name.inspect} were to be fired.",
297
- '@param [Hash] requirements The transition requirements to test against',
298
- "@option requirements [#{state_type}] :from (the current state) One or more initial states",
299
- "@option requirements [#{state_type}] :to One or more target states",
300
- '@option requirements [Boolean] :guard Whether to guard transitions with conditionals',
301
- '@return [StateMachines::Transition] The transition that would be performed or +nil+'
302
- ]
303
- m.parameters = [['requirements', '{}']]
304
-
305
- # Fire event
306
- register(m = ::YARD::CodeObjects::MethodObject.new(namespace, event.qualified_name))
307
- m.docstring = [
308
- "Fires the #{event.name.inspect} event.",
309
- '@param [Array] args Optional arguments to include in transition callbacks',
310
- '@return [Boolean] +true+ if the transition succeeds, otherwise +false+'
311
- ]
312
- m.parameters = ['*args']
313
-
314
- # Fire event (raises exception)
315
- register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "#{event.qualified_name}!"))
316
- m.docstring = [
317
- "Fires the #{event.name.inspect} event, raising an exception if it fails.",
318
- '@param [Array] args Optional arguments to include in transition callbacks',
319
- '@return [Boolean] +true+ if the transition succeeds',
320
- '@raise [StateMachines::InvalidTransition] If the transition fails'
321
- ]
322
- m.parameters = ['*args']
310
+ next if inherited_machine&.events&.[](event.name)
311
+
312
+ define_event_query_methods(event)
313
+ define_event_fire_methods(event)
323
314
  end
324
315
  end
325
316
 
317
+ def define_event_query_methods(event)
318
+ requirements = ['@param [Hash] requirements The transition requirements to test against',
319
+ "@option requirements [#{state_type}] :from One or more initial states",
320
+ "@option requirements [#{state_type}] :to One or more target states",
321
+ '@option requirements [Boolean] :guard Whether to guard transitions with conditionals']
322
+
323
+ document_method("can_#{event.qualified_name}?",
324
+ ["Checks whether #{event.name.inspect} can be fired.", *requirements,
325
+ "@return [Boolean] +true+ if #{event.name.inspect} can be fired, otherwise +false+"],
326
+ parameters: [%w[requirements {}]])
327
+ document_method("#{event.qualified_name}_transition",
328
+ ["Gets the next transition that would be performed if #{event.name.inspect} " \
329
+ 'were to be fired.', *requirements,
330
+ '@return [StateMachines::Transition] The transition that would be performed or +nil+'],
331
+ parameters: [%w[requirements {}]])
332
+ end
333
+
334
+ def define_event_fire_methods(event)
335
+ args = '@param [Array] args Optional arguments to include in transition callbacks'
336
+
337
+ description = Description.docstring_lines(@events.fetch(event.name.to_s))
338
+
339
+ document_method(event.qualified_name,
340
+ ["Fires the #{event.name.inspect} event.", *description, args,
341
+ '@return [Boolean] +true+ if the transition succeeds, otherwise +false+'],
342
+ parameters: ['*args'])
343
+ document_method("#{event.qualified_name}!",
344
+ ["Fires the #{event.name.inspect} event, raising an exception if it fails.", *description,
345
+ args,
346
+ '@return [Boolean] +true+ if the transition succeeds',
347
+ '@raise [StateMachines::InvalidTransition] If the transition fails'],
348
+ parameters: ['*args'])
349
+ end
350
+
326
351
  # Defines auto-generated state methods for the given machine
327
352
  def define_state_methods
328
353
  machine.states.each do |state|
329
- next if inherited_machine && inherited_machine.states[state.name] || !state.name
330
-
331
- # State query
332
- register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "#{state.qualified_name}?"))
333
- m.docstring = [
334
- "Checks whether #{state.name.inspect} is the current state.",
335
- '@return [Boolean] +true+ if this is the current state, otherwise +false+'
336
- ]
354
+ next if inherited_machine&.states&.[](state.name) || !state.name
355
+
356
+ document_method("#{state.qualified_name}?",
357
+ ["Checks whether #{state.name.inspect} is the current state.",
358
+ '@return [Boolean] +true+ if this is the current state, otherwise +false+'])
337
359
  end
338
360
  end
339
361
  end