aws-flow 1.0.8 → 1.0.9

data/lib/aws/flow/fiber.rb

@@ -13,33 +13,40 @@
 # permissions and limitations under the License.
 ##
 
-# This file contains our implementation of fibers for 1.8
+# This file contains our implementation of fibers for 1.8.
 module AWS
   module Flow
     module Core
       require 'fiber'
+      # @api private
       class FlowFiber < Fiber
+        # @api private
         def initialize(*args)
           ObjectSpace.define_finalizer(self, self.class.finalize(self.object_id))
           super(args)
         end
+        # @api private
         class << self
           attr_accessor :local_variables
         end
         @local_variables = Hash.new {|hash, key| hash[key] = {}}
+        # @api private
         def self.finalize(obj_id)
           proc { FlowFiber.local_variables.delete(obj_id) }
         end
+        # @api private
         def self.[](index)
           self.local_variables[index]
         end
+        # @api private
         def self.[]=(key, value)
           self.local_variables[key] = value
         end
 
-        # Will unset all the values for ancestors of this fiber, assuming that
+        # Unsets all the values for ancestors of this fiber, assuming that
         # they have the same value for key. That is, they will unset upwards until
-        # the first time the value stored at key is changed
+        # the first time the value stored at key is changed.
+        # @api private
         def self.unset(current_fiber, key)
           current_value = FlowFiber[current_fiber.object_id][key]
           parent = FlowFiber[current_fiber.object_id][:parent]
@@ -54,8 +61,9 @@ module AWS
           FlowFiber[current_fiber.object_id].delete(key)
         end
 
+        # @api private
         def initialize
-          # Child fibers should inherit their parents FiberLocals
+          # Child fibers should inherit their parents FiberLocals.
           FlowFiber[Fiber.current.object_id].each_pair do |key, val|
             FlowFiber[self.object_id][key] = val
           end
@@ -63,15 +71,15 @@ module AWS
           super
         end
 
+        # @api private
         def [](key)
           FlowFiber[self.object_id][key]
         end
+        # @api private
         def []=(key, value)
           FlowFiber[self.object_id][key] = value
         end
-
       end
-
     end
   end
 end

data/lib/aws/flow/flow_utils.rb

@@ -17,7 +17,9 @@
 module AWS
   module Flow
     module Core
+      # @api private
       class IllegalStateException < Exception; end
+      # @api private
       class CancellationException < Exception
         attr_accessor :reason, :details
         def initialize(reason = nil, details = nil)
@@ -26,14 +28,15 @@ module AWS
         end
       end
 
+      # @api private
       def make_backtrace(parent_backtrace)
-        # 1 frame for the function that actually removes the stack traces
+        # 1 frame for the function that actually removes the stack traces.
         # 1 frame for the function that calls into the function that removes
-        # frames in AsyncBacktrace
-        # 1 frame for the call into this function
-        # 1 frame for the initialize call of the BRE or External Task
-        # 1 frame for the new call into the BRE or ET
-        # 1 frame for the AsyncScope initialize that the BRE/ET has to be in
+        # frames in AsyncBacktrace.
+        # 1 frame for the call into this function.
+        # 1 frame for the initialize call of the BeginRescueEnsure or ExternalTask.
+        # 1 frame for the new call into the BeginRescueEnsure or ExternalTask.
+        # 1 frame for the AsyncScope initialize that the BeginRescueEnsure/ExternalTask has to be in.
 
         # "./lib/aws/rubyflow/asyncBacktrace.rb:75:in `caller'"
         # "./lib/aws/rubyflow/asyncBacktrace.rb:21:in `create'"

data/lib/aws/flow/future.rb

@@ -20,17 +20,23 @@ module AWS
     module Core
       class AlreadySetException < Exception; end
 
-      # A Future represents the result of an asynchronous computation. Methods are
-      # provided to check if the computation is complete(Future#set), to wait for
-      # its completion(Future#wait), and to retrieve the result of the
-      # computation(Future#get). The result can only be retrieved using method get
-      # when the computation has completed, blocking if necessary until it is
-      # ready. This is okay, however, because it will block that Fiber, and
-      # another Fiber will start executing
+      # Represents the result of an asynchronous computation. Methods are
+      # provided to:
+      #
+      # * retrieve the result of the computation, once it is complete ({Future#get}).
+      # * check if the computation is complete ({Future#set?})
+      # * execute a block when computation is complete ({Future#on_set})
+      #
+      # The result of a Future can only be retrieved when the computation has
+      # completed.  {Future#get} blocks execution, if necessary, until the
+      # Future is ready.  This is okay: because it will block that fiber,
+      # another fiber will start executing.
+      #
       class Future
 
-        # Sets the value of the future, and notifies all of the Fibers that tried
-        # to get when this future wasn't ready.
+        # Sets the value of the {Future}, and notifies all of the fibers that
+        # tried to call {#get} when this future wasn't ready.
+        # @api private
         def set(result=nil)
           raise AlreadySetException if @set
           @set = true
@@ -40,14 +46,21 @@ module AWS
           self
         end
 
-        # determines whether the object is a flow future. The contract is that
-        # flow futures must have a #get method.
+        # Is the object is an AWS Flow future? AWS Flow futures *must* have a
+        # {#get} method.
+        # @api private
         def is_flow_future?
           true
         end
 
-        # Blocks if Future is not set
-        # raises CancellationError when task is cancelled
+        # Blocks if future is not set. Returns the result of the future once
+        # {#set} is true.
+        #
+        # @return
+        #   The result of the future.
+        #
+        # @raise CancellationError
+        #   when the task is cancelled.
         def get
           until @set
             @conditional ||= FiberConditionVariable.new
@@ -56,16 +69,22 @@ module AWS
           @result
         end
 
+        # @return
+        #   true if the {Future} has been set.
         def set?
           @set
         end
 
+        # Unsets the future.
+        #
+        # @api private
         def unset
           @set = nil
           @result = nil
         end
 
-        # Add a callback, block, which will fire when the future is set
+        # Adds a callback, passed in as a block, which will fire when the future
+        # is set.
         def on_set(&block)
           @listeners ||= []
           # TODO probably want to use lambda here
@@ -73,19 +92,23 @@ module AWS
         end
       end
 
-      # Based on the ruby core source:
+      # Represents a fiber condition variable.
+      # Based on the Ruby core source:
       # https://github.com/ruby/ruby/blob/trunk/lib/thread.rb
+      # @api private
       class FiberConditionVariable
         #
         # Creates a new ConditionVariable
         #
+        # @api private
         def initialize
           @waiters = []
         end
 
-
-        # Have the current fiber wait on this condition variable, and wake up when
-        # the FiberConditionVariable is signalled/broadcaster
+        # Have the current fiber wait on this condition variable, and wake up
+        # when the FiberConditionVariable is signaled/broadcasted.
+        #
+        # @api private
         def wait
           fiber = ::Fiber.current
           @waiters << fiber
@@ -96,6 +119,7 @@ module AWS
         #
         # Wakes up the first fiber in line waiting for this lock.
         #
+        # @api private
         def signal
           t = @waiters.shift
           t.schedule if t && t.alive?
@@ -105,6 +129,7 @@ module AWS
         #
         # Wakes up all fibers waiting for this lock.
         #
+        # @api private
         def broadcast
           signal until @waiters.empty?
           self

data/lib/aws/flow/implementation.rb

@@ -13,17 +13,22 @@
 # permissions and limitations under the License.
 #++
 
-# This file contains the externally visible parts of flow that are expected to be used by customers of flow
+# This file contains the externally visible parts of flow that are expected to be used by customers of flow.
 module AWS
   module Flow
     module Core
+
+      # A basic exception class with no context.
       class NoContextException < Exception; end
 
+      # @param [Future] future
+      #   Unused; defaults to **nil**.
+      #
       # @param block
       #   The block of code to be executed when the task is run.
       #
       # @raise [NoContextException]
-      #   If the current fiber does not respond to {#__context__}.
+      #   If the current fiber does not respond to `Fiber.__context__`.
       #
       # @return [Future]
       #   The tasks result, which is a {Future}.
@@ -46,7 +51,7 @@ module AWS
       #   The tasks result, which is a {Future}.
       #
       # @raise [NoContextException]
-      #   If the current fiber does not respond to {#__context__}.
+      #   If the current fiber does not respond to `Fiber.__context__`.
       #
       def daemon_task(&block)
         fiber = ::Fiber.current
@@ -65,7 +70,7 @@ module AWS
       # @return [nil]
       #
       # @raise [NoContextException]
-      #   If the current fiber does not respond to {#__context__}.
+      #   If the current fiber does not respond to `Fiber.__context__`.
       #
       def external_task(&block)
         fiber = ::Fiber.current
@@ -77,15 +82,17 @@ module AWS
         nil
       end
 
-
+      # Creates a new error handler for asynchronous tasks.
+      #
+      # @param block
+      #   A block that defines the {BeginRescueEnsure#begin}, {BeginRescueEnsure#rescue}, and {BeginRescueEnsure#ensure}
+      #   methods.
       #
+      # @return
+      #   The result of the `begin` statement if there is no error; otherwise the value of the `return` statement.
       #
-      # * *Args*    :
-      #   - block -> a block, which is passed in a BeginRescueEnsureWrapper, and which will define the BeginRescueEnsure#begin, BeginRescueEnsure#rescue, and BeginRescueEnsure#ensure methods
-      # * *Returns* :
-      #   - The result of the begin statement, if there is no error, otherwise the value of the return statement
-      # * *Raises* :
-      #   - +NoContextException+ -> If the current fiber does not respond to #__context__
+      # @raise [NoContextException]
+      #   If the current fiber does not respond to `Fiber.__context__`.
       #
       def error_handler(&block)
         fiber = ::Fiber.current
@@ -98,15 +105,24 @@ module AWS
         begin_rescue_ensure
       end
 
-      # @param block
-      #   A code block, which is passed within a {BeginRescueEnsureWrapper}, and which must define the
-      #   {BeginRescueEnsure#begin}, {BeginRescueEnsure#rescue}, and {BeginRescueEnsure#ensure} methods.
-      # @!visibility private
+      # @api private
+      #
       def _error_handler(&block)
         error_handler(&block).result
       end
 
 
+      # Waits for the passed-in function to complete, setting values for the provided futures when it does.
+      #
+      # @param function
+      #   The function to wait for.
+      #
+      # @param [Array<Future>] futures
+      #   A list of futures to provide values for when the function completes.
+      #
+      # @return [Array<Future>]
+      #   A list of the set futures, in the order of being set.
+      #
       def wait_for_function(function, *futures)
         conditional = FiberConditionVariable.new
         futures.flatten!
@@ -125,10 +141,10 @@ module AWS
 
       # Blocks until *any* of the arguments are set.
       #
-      # @param [Array] futures
+      # @param [Array<Future>] futures
       #   A list of futures to wait for. The function will return when at least one of these is set.
       #
-      # @return [Array]
+      # @return [Array<Future>]
       #   A list of the set futures, in the order of being set.
       #
       def wait_for_any(*futures)
@@ -140,7 +156,7 @@ module AWS
       # @param [Array<Future>] futures
       #   A list of futures to wait for. The function will return only when all of them are set.
       #
-      # @return [Array]
+      # @return [Array<Future>]
       #   A list of the set futures, in the order of being set.
       #
       def wait_for_all(*futures)

data/lib/aws/flow/simple_dfa.rb

@@ -17,16 +17,18 @@ module AWS
   module Flow
     module Core
 
-      # Contains a Data Flow Analysis (DFA)-like framework, where transition functions can perform arbitrary computation
-      # before moving to the next state
+      # Contains a data flow analysis (DFA)-like framework, where transition functions can perform arbitrary computation
+      # before moving to the next state.
+      # @api private
       module SimpleDFA
         attr_accessor :transitions, :symbols, :states, :start_state
 
-        # Creates a new SimpleDFA instance.
+        # Creates a new `SimpleDFA` instance.
         #
         # @param start_state
         #   The state with which to start the framework.
         #
+        # @api private
         def init(start_state)
           include InstanceMethods
           @start_state = start_state
@@ -39,6 +41,7 @@ module AWS
         # @return the start state
         #   The start state that was provided when this instance was created.
         #
+        # @api private
         def get_start_state
           @start_state
         end
@@ -46,10 +49,12 @@ module AWS
         # @return [Array]
         #   The list of all transitions that were added with {#add_transition}.
         #
+        # @api private
         def get_transitions
           @transitions
         end
 
+        # @api private
         def define_general(state, &block)
           @symbols.each do |symbol|
             if @transitions[[state, symbol]].nil?
@@ -58,19 +63,23 @@ module AWS
           end
         end
 
+        # @api private
         def add_transition(state, symbol, &block)
           @symbols << symbol unless @symbols.include? symbol
           @states << state unless @states.include? state
           @transitions[[state, symbol]] = block
         end
 
+        # @api private
         def uncovered_transitions
           @states.product(@symbols) - @transitions.keys
         end
 
+        # @api private
         module InstanceMethods
           attr_accessor :current_state
 
+          # @api private
           def consume(symbol)
             @current_state ||= self.class.get_start_state
             func_to_call = self.class.get_transitions[[@current_state, symbol]]
@@ -79,7 +88,6 @@ module AWS
           end
         end
       end
-
     end
   end
 end

data/lib/aws/flow/tasks.rb

@@ -13,37 +13,48 @@
 # permissions and limitations under the License.
 ##
 
-# Contains all the task methods, which allow arbitrary blocks of code to be run asynchronously
+# Contains all the task methods, which allow arbitrary blocks of code to be run asynchronously.
 
 module AWS
   module Flow
     module Core
+      # @api private
       class Task < FlowFiber
         attr_reader :result, :block
         attr_accessor :backtrace, :__context__, :parent
 
-        # Creates a new Task.
+        # Creates a new task.
         #
         # @param __context__
-        #   A Task needs a reference to the __context__ that created it so that when the "task" macro is called it can
-        #   find the __context__ which the new Task should be added to.
+        #   A task needs a reference to the __context__ that created it so that when the "task" macro is called it can
+        #   find the __context__, which the new task should be added to.
         #
         # @param block
         #   A block of code that will be run by the task.
         #
+        # @api private
         def initialize(__context__, &block)
           @__context__ = __context__
           @result = Future.new
           @block = block
 
           # Is the task alive?
+          #
+          # @return Boolean
+          #   true if the task is alive and has not been canceled.
+          #
+          # @api private
           def alive?
             super && !@cancelled
             #!!@alive# && !@cancelled
           end
 
+          # Retrieves the executor for this task.
+          #
           # @return
           #   The executor for this task.
+          #
+          # @api private
           def executor
             @__context__.executor
           end
@@ -51,7 +62,7 @@ module AWS
           super() do
             begin
               # Not return because 1.9 will freak about local jump problems if you
-              # try to return, as this is inside a block
+              # try to return, as this is inside a block.
               next if @cancelled
               @result.set(lambda(&block).call)
               next if @cancelled
@@ -68,32 +79,37 @@ module AWS
         end
 
         #
-        # Passes the get_heirs calls to the context, to ensure uniform handling of get_heirs
+        # Passes all `get_heirs` calls to the class that is holding the context,
+        # to ensure uniform handling of `get_heirs`.
         #
+        # @api private
         def get_heirs
           @__context__.get_heirs
         end
 
+        # Will always be false. Provides a common API for BeginRescueEnsure to
+        # ensure they are maintaining their nonDaemonHeirsCount correctly.
         #
-        # Returns true/false, depending on if we are in a daemon task or not
-        #
+        # @api private
         def is_daemon?
           return false
         end
 
-        # Used by Future#signal to schedule the task for re-evaluation.
+        # Used by {Future#signal} to schedule the task for re-evaluation.
         #
         # This will simply add the task back to the list of things to be run in the parent's event loop.
         #
+        # @api private
         def schedule
           @__context__ << self
         end
 
-        # Cancel will prevent the execution of this particular task, if possible
+        # Prevents the execution of this particular task, if possible.
         #
         # @param error
-        #   The error that is the cause of the cancellation
+        #   The error that is the cause of the cancellation.
         #
+        # @api private
         def cancel(error)
           @cancelled = true
           @__context__.remove(self)
@@ -102,9 +118,9 @@ module AWS
         # Fails the given task with the specified error.
         #
         # @param error
-        #   The error that is the cause of the cancellation
+        #   The error that is the cause of the failure.
         #
-        # @!visibility private
+        # @api private
         def fail(this_task, error)
           @__context__.fail(this_task, error)
         end
@@ -112,73 +128,80 @@ module AWS
         #   raise error
         # end
 
-        # Adds a task to this task's context
+        # Adds a task to this task's context.
         #
         # @param this_task
         #   The task to add.
         #
+        # @api private
         def <<(this_task)
           @__context__.parent << this_task
         end
 
-        # Removes a task from this task's context
+        # Removes a task from this task's context.
         #
         # @param this_task
         #   The task to remove.
         #
+        # @api private
         def remove(this_task)
           @__context__.remove(this_task)
         end
-
-
       end
 
-
-      # Similar to a regular Task in all functioning except that it is not assured a chance to execute. Whereas a
-      # begin/run/execute block cannot be closed out while there are still nonDaemonHeirs, it can happily entered the
-      # closed state with daemon heirs, making them essentially unrunnable.
+      # Represents a task that might not execute. Similar to a regular task in
+      # all functions except that it is not assured a chance to execute. Whereas
+      # a begin/run/execute block cannot be closed while there are still
+      # `nonDaemonHeirs`, a DaemonTask can enter the closed state with daemon
+      # heirs, making them essentially unrunnable.
+      #
+      # @api private
       class DaemonTask < Task
-
+        # @api private
         def is_daemon?
           return true
         end
-
       end
 
-      # External Tasks are used to bridge asynchronous execution to external asynchronous APIs or events. It is passed a block, like so
+      # Used to bridge asynchronous execution to external asynchronous APIs or
+      # events. It is passed a block, like so:
       #
       #     external_task do |t|
       #       t.cancellation_handler { |h, cause| h.fail(cause) }
       #       t.initiate_task { |h| trace << :task_started; h.complete; }
       #     end
       #
-      # The {ExternalTask#initiate_task} method is expected to call an external API and return without blocking.
-      # Completion or failure of the external task is reported through ExternalTaskCompletionHandle, which is passed into
-      # the initiate_task and cancellation_handler blocks. The cancellation handler, defined in the same block as the
-      # initiate_task, is used to report the cancellation of the external task.
+      # The {ExternalTask#initiate_task} method is expected to call an external
+      # API and return without blocking.  Completion or failure of the external
+      # task is reported through ExternalTaskCompletionHandle, which is passed
+      # into the initiate_task and cancellation_handler blocks. The cancellation
+      # handler, defined in the same block as the initiate_task, is used to
+      # report the cancellation of the external task.
       #
+      # @api private
       class ExternalTask < FlowFiber
         attr_reader :block
         attr_accessor :cancelled, :inCancellationHandler, :parent, :backtrace, :__context__
 
 
-        # Will always be false, provides a common api for BRE's to ensure they are maintaining their nonDaemonHeirsCount
-        # correctly
-        # @!visibility private
+        # Will always be false, provides a common API for BeginRescueEnsure's to
+        # ensure they are maintaining their nonDaemonHeirsCount correctly.
+        #
+        # @api private
         def is_daemon?
           false
         end
 
         #
-        #  Passes the get_heirs calls to the context, to ensure uniform handling of
-        #  get_heirs
+        # Passes the get_heirs calls to the context, to ensure uniform handling
+        # of get_heirs
         #
-        # @!visibility private
+        # @api private
         def get_heirs
           @__context__.get_heirs
         end
 
-        # @!visibility private
+        # @api private
         def initialize(options = {}, &block)
           @inCancellationHandler = false
           @block = block
@@ -188,43 +211,47 @@ module AWS
           block.call(self)
         end
 
-        # This method is here because the way we create ExternalTasks is a little
-        # tricky - if the parent isn't passed in on construction(as is the case with
-        # the external_task function), then the parent will only be set after
-        # ExternalTask#initialize is called. We'd prefer to set it in the initiailze,
-        # however, the backtrace relies on the parent's backtrace, and so we cannot do
-        # that. Instead, we use this method to lazily create it, when it is
-        # called. The method itself simply sets the backtrace to the the
-        # make_backtrace of the parent's backtrace, if the backtrace is not already
-        # set, and will otherwise simply return the backtrace
-        # @!visibility private
+        # This method is here because the way we create external tasks is a
+        # little tricky. If the parent isn't passed in on construction(as is the
+        # case with the external_task function), then the parent will only be
+        # set after ExternalTask#initialize is called. We'd prefer to set it in
+        # initialize, however, the backtrace relies on the parent's backtrace,
+        # and so we cannot do that. Instead, we use this method to lazily create
+        # it when it is called. The method itself simply sets the backtrace to
+        # the make_backtrace of the parent's backtrace, if the backtrace is not
+        # already set, and will otherwise simply return the backtrace
+        #
+        # @api private
         def backtrace
           @backtrace ||= make_backtrace(@parent.backtrace)
         end
 
-        # Add a task which removes yourself, and pass it through the parents executor
-        # @!visibility private
+        # Add a task that removes yourself, and pass it through the parents executor.
+        #
+        # @api private
         def remove_from_parent
           @__context__.executor << FlowFiber.new { @parent.remove(self) }
         end
 
-        # Add a task which fails yourself with the suppiled error, and pass it through
-        # the parents executor
-        # @!visibility private
+        # Add a task that fails yourself with the suppiled error, and pass it
+        # through the parents executor.
+        #
+        # @api private
         def fail_to_parent(error)
           @__context__.executor << FlowFiber.new { @parent.fail(self, error) }
         end
 
 
-        # Part of the interface provided by Fiber, has to overridden to properly
-        # reflect that an ExternalTasks alive-ness relies on it's
-        # ExternalTaskCompletionHandle
-        # @!visibility private
+        # Part of the interface provided by fiber, has to overridden to properly
+        # reflect that an external tasks alive-ness relies on its
+        # ExternalTaskCompletionHandle.
+        #
+        # @api private
         def alive?
           ! @handle.completed
         end
 
-        # @!visibility private
+        # @api private
         def cancel(cause)
           return if @cancelled
           return if @handle.failure != nil || @handle.completed
@@ -252,20 +279,23 @@ module AWS
           end
         end
 
-        # Store the cancellation handler block passed in for later reference
-        # @!visibility private
+        # Store the passed-in cancellation handler block for later reference.
+        #
+        # @api private
         def cancellation_handler(&block)
           @cancellation_task = lambda { |cause| block.call(@handle, cause) }
         end
 
-        # Store the block passed in for later
-        # @!visibility private
+        # Store the passed-in block for later.
+        #
+        # @api private
         def initiate_task(&block)
           @initiation_task = lambda { block.call(@handle) }
         end
 
-        # From the interface provided by Fiber, will execute the External Task
-        # @!visibility private
+        # From the interface provided by fiber, will execute the external task.
+        #
+        # @api private
         def resume
           return if @cancelled
           begin
@@ -279,27 +309,28 @@ module AWS
       end
 
       # Used to complete or fail an external task initiated through
-      # ExternalTask#initiate_task, and thus handles the logic of what to do when the
-      # external task is failed.
-      # @!visibility private
+      # ExternalTask#initiate_task, and thus handles the logic of what to do
+      # when the external task is failed.
+      #
+      # @api private
       class ExternalTaskCompletionHandle
         attr_accessor :completed, :failure, :external_task
 
-        # @!visibility private
+        # @api private
         def initialize(external_task)
           @external_task = external_task
         end
 
-        # Will merge the backtrace, set the @failure, and then fail the task from the parent
-        # @!visibility private
+        # Merges the backtrace, sets the @failure, and then fails the task from
+        # the parent.
         #
         # @param error
-        #   The exception to fail on
+        #   The exception to fail on.
         #
         # @raise IllegalStateException
-        #   Raises if failure hasn't been set, or if the task is already completed
+        #   Raises if failure hasn't been set, or if the task is already completed.
         #
-        # @!visibility private
+        # @api private
         def fail(error)
           if ! @failure.nil?
             raise IllegalStateException, "Invalid ExternalTaskCompletionHandle"
@@ -320,12 +351,12 @@ module AWS
           end
         end
 
-        # Set's the task to complete, and removes it from it's parent
+        # Sets the task to complete, and removes it from its parent.
         #
         # @raise IllegalStateException
-        #   If the failure hasn't been set, or if the task is already completed
+        #   If the failure hasn't been set, or if the task is already completed.
         #
-        # @!visibility private
+        # @api private
         def complete
           if ! failure.nil?
             raise IllegalStateException, ""
@@ -339,15 +370,19 @@ module AWS
         end
       end
 
-      # TaskContext is the class that holds some meta-information for tasks, and which stores the parent link for tasks.
-      # It seperates some of the concerns between tasks and what they have to know to follow back up the chain.
+      # Holds some metadata for tasks and stores the parent link for tasks.  It
+      # separates some of the concerns between tasks and what they have to know
+      # to follow back up the chain.
       #
-      #  All the methods here will simply delegate calls, either up to the parent, or down to the task
-      # @!visibility private
+      # All the methods here will simply delegate calls, either up to the
+      # parent, or down to the task.
+      #
+      # @api private
       class TaskContext
 
         attr_accessor :daemon, :parent, :backtrace, :cancelled
 
+        # @api private
         def initialize(options = {})
           @parent = options[:parent]
           @task = options[:task]
@@ -356,49 +391,48 @@ module AWS
           @daemon = options[:daemon]
         end
 
-        # @!visibility private
+        # @api private
         def get_closest_containing_scope
           @task
           # @ parent
         end
 
-        # @!visibility private
+        # @api private
         def alive?
           @task.alive?
         end
 
-        # @!visibility private
+        # @api private
         def executor
           @parent.executor
         end
 
-        # @!visibility private
+        # @api private
         def get_heirs
           str = "I am a #{@task.class}
         and my block looks like #{@task.block}"
         end
 
-        # @!visibility private
+        # @api private
         def fail(this_task, error)
           @parent.fail(this_task, error)
         end
 
-        # @!visibility private
+        # @api private
         def remove(thread)
           @parent.remove(thread)
         end
 
-        # @!visibility private
+        # @api private
         def cancel(error_type)
           @task.cancelled = true
           @parent.cancel(self)
         end
 
-        # @!visibility private
+        # @api private
         def <<(task)
           @parent << task
         end
-
       end
     end
   end