Bug 589085 - Document the errors module. r=atul, a0.7=myk (from bug 569708 comment 4)
authorDrew Willcoxon <adw@mozilla.com>
Mon, 23 Aug 2010 19:26:16 -0700
changeset 759 9cc530cc79dcd8136f0c25d27f8ae4c60c874330
parent 758 cc8e33ef9ff75e7ca23636b3bbd7f81353c1b41e
child 760 fd065f7b5bb649264a589bc0f504dece85e6562f
push id284
push userdwillcoxon@mozilla.com
push dateTue, 24 Aug 2010 02:26:44 +0000
reviewersatul
bugs589085, 569708
Bug 589085 - Document the errors module. r=atul, a0.7=myk (from bug 569708 comment 4)
packages/jetpack-core/docs/errors.md
new file mode 100644
--- /dev/null
+++ b/packages/jetpack-core/docs/errors.md
@@ -0,0 +1,42 @@
+<!-- contributed by Drew Willcoxon [adw@mozilla.com] -->
+
+The `errors` module provides helpers for safely invoking user callbacks.
+
+
+Functions
+---------
+
+<api name="catchAndLog">
+@function
+  Wraps a callback in a function that when invoked will catch and log any
+  exception thrown by the callback.
+@param callback {function}
+  The callback to wrap.
+@param [defaultResponse] {value}
+  This value will be returned by the wrapper if `callback` throws an exception.
+  If not given, `undefined` is used.
+@param [logException] {function}
+  When `callback` throws an exception, it will be passed to this function.  If
+  not given, the exception is logged using `console.exception()`.
+@returns {function}
+  A function that will invoke `callback` when called.  The return value of this
+  function is the return value of `callback` unless `callback` throws an
+  exception.  In that case, `defaultResponse` is returned or `undefined` if
+  `defaultResponse` is not given.
+</api>
+
+<api name="catchAndLogProps">
+@function
+  Replaces methods of an object with wrapped versions of those methods returned
+  by `catchAndLog()`.
+@param object {object}
+  The object whose methods to replace.
+@param props {string,array}
+  The names of the methods of `object` to replace, either a string for a single
+  method or an array of strings for multiple methods.
+@param [defaultResponse] {value}
+  This value will be returned by any wrapper whose wrapped method throws an
+  exception.  If not given, `undefined` is used.
+@param [logException] {function}
+  See `catchAndLog()`.
+</api>