From 4cb1f6c509aacd0ff08d134b2b9ee570b428eb05 Mon Sep 17 00:00:00 2001
From: Matt Colyer <mcolyer@github.com>
Date: Mon, 26 Aug 2013 16:49:07 -0700
Subject: [PATCH] Add comments to Task

---
 src/task.coffee | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/src/task.coffee b/src/task.coffee
index 361027464..6cfa04c27 100644
--- a/src/task.coffee
+++ b/src/task.coffee
@@ -5,18 +5,46 @@ EventEmitter = require 'event-emitter'
 # Public: Run a node script in a separate process.
 #
 # Used by the fuzzy-finder.
+#
+# ## Events
+#
+# * task:log - Emitted when console.log is called within the task.
+# * task:warn - Emitted when console.warn is called within the task.
+# * task:error - Emitted when console.error is called within the task.
+# * task:complete - Emitted when the task has succeeded or failed.
 module.exports =
 class Task
+<<<<<<< HEAD
   _.extend @prototype, EventEmitter
 
+=======
+  # Public: A helper method to easily launch and run a task once.
+  #
+  # * taskPath:
+  #   The path to the Coffeescript/Javascript file which exports a single
+  #   function to execute.
+  # * args:
+  #   The Array of arguments to pass to the exported function.
+>>>>>>> Add comments to Task
   @once: (taskPath, args...) ->
     task = new Task(taskPath)
     task.one 'task:completed', -> task.terminate()
     task.start(args...)
     task
 
+  # Public: Called upon task completion.
+  #
+  # It receives the same arguments that were passed to the task.
+  #
+  # If subclassed, this is intended to be overridden. However if {.start}
+  # receives a completion callback, this is overridden.
   callback: null
 
+  # Public: Creates a task.
+  #
+  # * taskPath:
+  #   The path to the Coffeescript/Javascript file that exports a single
+  #   function to execute.
   constructor: (taskPath) ->
     bootstrap = """
       require('coffee-script');
@@ -41,11 +69,18 @@ class Task
 
     @handleEvents()
 
+  # Private: Routes messages from the child to the appropriate event.
   handleEvents: ->
     @childProcess.removeAllListeners()
     @childProcess.on 'message', ({event, args}) =>
       @trigger(event, args...)
 
+  # Public: Starts the task.
+  #
+  # * args:
+  #   The Array of arguments to pass to the function exported by the script. If
+  #   the last argument is a function, its removed from the array and called
+  #   upon completion (and replaces the complete function on the task instance).
   start: (args...) ->
     throw new Error("Cannot start terminated process") unless @childProcess?
 
@@ -53,6 +88,9 @@ class Task
     @callback = args.pop() if _.isFunction(args[args.length - 1])
     @childProcess.send({args})
 
+  # Public: Forcefully stop the running task.
+  #
+  # No events are emitted.
   terminate: ->
     return unless @childProcess?