improved timeout example, fixes #1264

lib/timeout.js

@@ -16,12 +16,31 @@ import initialParams from './internal/initialParams';
  * @param {*} [info] - Any variable you want attached (`string`, `object`, etc)
  * to timeout Error for more information..
  * @returns {Function} Returns a wrapped function that can be used with any of
- * the control flow functions.
+ * the control flow functions. Invoke this function with the same
+ * parameters as you would `asyncFunc`.
  * @example
  *
- * async.timeout(function(callback) {
- *     doAsyncTask(callback);
- * }, 1000);
+ * function myFunction(foo, callback) {
+ *     doAsyncTask(foo, function(err, data) {
+ *         // handle errors
+ *         if (err) return callback(err);
+ *
+ *         // do some stuff ...
+ *
+ *         // return processed data
+ *         return callback(null, data);
+ *     });
+ * }
+ *
+ * var wrapped = async.timeout(myFunction, 1000);
+ *
+ * // call `wrapped` as you would `myFunction`
+ * wrapped({ bar: 'bar' }, function(err, data) {
+ *     // if `myFunction` takes < 1000 ms to execute, `err`
+ *     // and `data` will have their expected values
+ *
+ *     // else `err` will be an Error with the code 'ETIMEDOUT'
+ * });
  */
 export default function timeout(asyncFn, milliseconds, info) {
     var originalCallback, timer;