action.rb in upgrow-0.0.4

- old
+ new

@@ -1,23 +1,23 @@
 # frozen_string_literal: true
 
 require_relative 'result'
 
 module Upgrow
-  # Actions represent the entry points to the app’s core logic. These objects
+  # Actions represent the entry points to the app's core logic. These objects
   # coordinate workflows in order to get operations and activities done.
-  # Ultimately, Actions are the public interface of the app’s business layers.
+  # Ultimately, Actions are the public interface of the app's business layers.
   #
-  # Rails controllers talk to the app’s internals by sending messages to
+  # Rails controllers talk to the app's internals by sending messages to
   # specific Actions, optionally with the required inputs. Actions have a
   # one-to-one relationship with incoming requests: they are paired
   # symmetrically with end-user intents and demands. This is quite a special
   # requirement from this layer: any given HTTP request handled by the app
   # should be handled by a single Action.
   #
   # The fact that each Action represents a meaningful and complete
-  # request-response cycle forces modularization for the app’s business logic,
+  # request-response cycle forces modularization for the app's business logic,
   # exposing immediately complex relationships between objects at the same time
   # that frees up the app from scenarios such as interdependent requests. In
   # other words, Actions do not have knowledge or coupling between other Actions
   # whatsoever.
   #
@@ -27,9 +27,14 @@
   class Action
     # Module to be prepended to subclasses of Action. This allows Action to
     # decorate methods implemented by subclasses so they can have additional
     # behaviour.
     module Decorator
+      # Calls the original `perform` method of the Action object and returns its
+      # Result. In case the Action throws a `:failure`, catches and returns its
+      # value, which is supposed to be a failed Result generated by the Action.
+      #
+      # @return [Result] the Action Result.
       def perform(...)
         catch(:failure) do
           super
           result
         end