From c711aaae5cde8691b1d33b6d4d9dae876a0ebfde Mon Sep 17 00:00:00 2001
From: zaneli <shun.otani@gmail.com>
Date: Thu, 24 Jul 2014 12:17:15 +0900
Subject: [PATCH] Add comments for bucks.js

---
 CONTRIBUTORS.md    |  1 +
 bucksjs/bucks.d.ts | 84 +++++++++++++++++++++++++++++++++++++++-------
 2 files changed, 72 insertions(+), 13 deletions(-)

diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
index e51d544d5..4a2d5d0ea 100644
--- a/CONTRIBUTORS.md
+++ b/CONTRIBUTORS.md
@@ -39,6 +39,7 @@ All definitions files include a header with the author and editors, so at some p
 * [Box2DWeb](http://code.google.com/p/box2dweb/) (by [Josh Baldwin](https://github.com/jbaldwin/))
 * [Breeze](http://www.breezejs.com/) (by [Boris Yankov](https://github.com/borisyankov))
 * [Browser Harness](https://github.com/scriby/browser-harness) (by [Chris Scribner](https://github.com/scriby))
+* [bucks.js](https://github.com/CyberAgent/bucks.js) (by [Shunsuke Ohtani](https://github.com/zaneli))
 * [CasperJS](http://casperjs.org) (by [Jed Hunsaker](https://github.com/jedhunsaker))
 * [Cheerio](https://github.com/MatthewMueller/cheerio) (by [Bret Little](https://github.com/blittle))
 * [Chosen](http://harvesthq.github.com/chosen/) (by [Boris Yankov](https://github.com/borisyankov))
diff --git a/bucksjs/bucks.d.ts b/bucksjs/bucks.d.ts
index 111665744..cac3c7121 100644
--- a/bucksjs/bucks.d.ts
+++ b/bucksjs/bucks.d.ts
@@ -7,47 +7,105 @@ declare module Bucks {
 
   interface BucksStatic {
 
+    /**
+     * bucks.js version.
+     */
     VERSION: string;
 
+    /**
+     * If set `true`, uncaught errors are logged.
+     */
     DEBUG: boolean;
 
+    /**
+     * Running bucks objects.
+     */
     running: Bucks[];
 
+    /**
+     * Not yet called `end` bucks object.
+     */
     living: Bucks[];
 
-    new (): Bucks;
+    /**
+     * Create bucks object.
+     */
+    new(): Bucks;
 
-    onError(onError:(err:Error, bucks:Bucks)=>any): void;
+    /**
+     * Catch all errors.
+     * @param onError Function called after catching error
+     */
+    onError(onError: (err:Error, bucks:Bucks)=>any): void;
   }
 
   interface Bucks {
 
-    add(task: Task): Bucks;
+    /**
+     * Add a task.
+     * @param task Function added async chain
+     */
+    add(task: TaskWithNext): Bucks;
 
-    then(onSuccess: (res:any, next?:Next)=>any): Bucks;
+    /**
+     * Add a task called only in case of success.
+     * @param onSuccess Function called only in case of success
+     */
+    then(onSuccess: (res:any, next?:Task)=>any): Bucks;
 
+    /**
+     * Add a empty task.
+     */
     empty(): Bucks;
 
-    error(onError: (err:Error, res:any, next?:Next)=>any): Bucks;
+    /**
+     * Add a task called only in case of error.
+     * @param onError Function called only in case of error
+     */
+    error(onError: (err:Error, next?:Task)=>any): Bucks;
 
-    parallel(tasks: Task[]): Bucks;
+    /**
+     * Add tasks in asynchronous way and join their results.
+     * @param tasks Functions called in asynchronous way and join their results
+     */
+    parallel(tasks: TaskWithNext[]): Bucks;
 
-    waterfall(tasks: Task[]): Bucks;
+    /**
+     * Add tasks in asynchronous way and join their results.
+     * @param tasks Functions added async chain
+     */
+    waterfall(tasks: TaskWithNext[]): Bucks;
 
+    /**
+     * Add delay execution.
+     * @param ms number millisecond for delaying
+     */
     delay(ms: number): Bucks;
 
+    /**
+     * Called when destroy async chain.
+     */
     dispose(): void;
 
-    destroy(err: Error): Bucks;
+    /**
+     * Destroy this object and call last callback function.
+     * @param err If specify err and no callback, throw to execute failure callback
+     */
+    destroy(err?: Error): Bucks;
 
-    end(callback?: (err?:Error, res?:any)=>any, errback?: (err:Error)=>any): void;
+    /**
+     * Complete creating async chain and start executing.
+     * @param callback Last callback function
+     * @param errback Handler for occurring error in last callback function
+     */
+    end(callback?: Task, errback?: (err:Error)=>any): void;
+  }
+
+  interface TaskWithNext {
+    (err?: Error, res?: any, next?: Task): any;
   }
 
   interface Task {
-    (err?: Error, res?: any, next?: Next): any;
-  }
-
-  interface Next {
     (err?: Error, res?: any): any;
   }
 }