Bug 569711 - convert unit-test.md to apidocs format. r=adw, a0.7=myk
authorNoelle Murata <fiveinchpixie@gmail.com>
Wed, 18 Aug 2010 17:40:04 -0700
changeset 736 1181b2cd0a3578fa8c99d16281d1a1b162634b27
parent 735 5ba38bd91643e5345ea2b2bb42edb001552a4ed2
child 737 9245d5e0202d7075da17af51dadf570ebcf41961
push id267
push userdwillcoxon@mozilla.com
push dateThu, 19 Aug 2010 00:40:49 +0000
reviewersadw
bugs569711
Bug 569711 - convert unit-test.md to apidocs format. r=adw, a0.7=myk
packages/jetpack-core/docs/unit-test.md
--- a/packages/jetpack-core/docs/unit-test.md
+++ b/packages/jetpack-core/docs/unit-test.md
@@ -1,94 +1,163 @@
+<!-- contributed by Atul Varma [atul@mozilla.com]  -->
+<!-- edited by Noelle Murata [fiveinchpixie@gmail.com]  -->
+
+
 The `unit-test` module makes it easy to find and run unit tests.
 
 ## Test Runner Objects ##
 
 Each function which represents a test case is passed a single argument
 `test`, which represents the test runner.  It has the following
 methods:
 
-<code>test.**pass**([*message*])</code>
+<api name="pass">
+@method
+  Marks a test as passing, with the given optional message.
 
-Marks a test as passing, with the given optional message.
+@param [message] {string}
+  Optional passing message.
+</api>
 
-<code>test.**fail**([*message*])</code>
+
+<api name="fail">
+@method
+  Marks a test as failing, with the given optional message.
 
-Marks a test as failing, with the given optional message.
+@param [message] {string}
+  Optional failure message.
+</api>
 
-<code>test.**exception**(*e*)</code>
 
-Marks a test as failing due to the given exception having been thrown.
-This can be put in a `catch` clause.
+<api name="exception">
+@method
+  Marks a test as failing due to the given exception having been thrown.
+  This can be put in a `catch` clause.
 
-<code>test.**assert**(*a*[, *message*])</code>
+@param e {exception}
+  An exception.
+</api>
+
+<api name="assert">
+@method
+  Ensures that `a` has a truthy value.
 
-Ensures that *a* has a truthy value.  A test is marked as passing or
-failing depending on the result, logging *message* with it.
+@param a {value}
+  Value to verify.
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+</api>
 
-<code>test.**assertEqual**(*a*, *b*[, *message*])</code>
+
+<api name="assertEqual">
+@method
+  Simply ensures that `a == b` without recursing into `a` or `b`.
+
+@param a {value}
+  A value.
 
-Simply ensures that *a* `==` *b* without recursing into
-*a* or *b*.  A test is marked as passing or failing depending on
-the result, logging *message* with it.
+@param b {value}
+  Another value.
+
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+</api>
 
-<code>test.**assertNotEqual**(*a*, *b*[, *message*])</code>
+<api name="assertNotEqual">
+@method
+  Simply ensures that `a != b` without recursing into `a` or `b`.
 
-Simply ensures that *a* `!=` *b* without recursing into
-*a* or *b*.  A test is marked as passing or failing depending on
-the result, logging *message* with it.
+@param a {value}
+  A value.
+
+@param b {value}
+  Another value.
 
-<code>test.**assertMatches**(*string*, *regexp*[, *message*])</code>
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+</api>
+
+
+<api name="assertMatches">
+@method
+  Ensures that the given string matches the given regular expression.
+  If it does, marks a test as passing, otherwise marks a test as
+  failing.
 
-Ensures that the given string matches the given regular expression.
-If it does, marks a test as passing, otherwise marks a test as
-failing.  *message* is logged with the pass or fail.
+@param string {string}
+  The string to test.
+
+@param regexp {regexp}
+  The string should match this regular expression.
 
-<code>test.**assertRaises**(*func*, *predicate*[, *message*])</code>
+@param [message] {string}
+  The test is marked as passing or failing depending on the result, logging
+  *message* with it.
+</api>
+
 
-Calls the function *func* with no arguments, expecting an exception
-to be raised. If nothing is raised, marks the test as failing. If an
-exception is raised, the exception's `message` property is
-compared with *predicate*: if *predicate* is a string, then a
-simple equality comparison is done with `message`. Otherwise,
-if *predicate* is a regular expression, `message` is tested
-against it. Depending on the outcome, a test is marked as passing or
-failing, and *message* is logged.
+<api name="assertRaises">
+@method
+  Calls the function `func` with no arguments, expecting an exception
+  to be raised. If nothing is raised, marks the test as failing. If an
+  exception is raised, the exception's `message` property is
+  compared with `predicate`: if `predicate` is a string, then a
+  simple equality comparison is done with `message`. Otherwise,
+  if `predicate` is a regular expression, `message` is tested
+  against it.
 
-<code>test.**waitUntilDone**([*timeout*])</code>
+@param func {function}
+  A function that should raise an exception when called.
+
+@param predicate {string,regexp}
+  A string or regular expression to compare to the exception's message.
+
+@param [message] {string}
+  Depending on the outcome, a test is marked as passing or failing, and
+  *message* is logged.
+</api>
 
-Puts the test runner into asynchronous testing mode, waiting up to
-*timeout* milliseconds for `test.done()` to be called.  This
-is intended for use in situations where a test suite schedules a
-callback, calls `test.waitUntilDone`, and then calls
-`test.done()` in the callback.
+
+<api name="waitUntilDone">
+@method
+  Puts the test runner into asynchronous testing mode, waiting up to
+  *timeout* milliseconds for `test.done()` to be called.  This
+  is intended for use in situations where a test suite schedules a
+  callback, calls `test.waitUntilDone()`, and then calls
+  `test.done()` in the callback.
 
-<code>test.**done**()</code>
+@param [timeout] {integer}
+  If this number of milliseconds elapses and `test.done()` has not yet been
+  called, the test is marked as failing.
+</api>
 
-Marks a test as being complete.  Assumes a previous call to
-`test.waitUntilDone()`.
+<api name="done">
+@method
+  Marks a test as being complete.  Assumes a previous call to
+  `test.waitUntilDone()`.
+</api>
+
 
 ## Functions ##
 
-<code>unit-test.**findAndRunTests**(*options*)</code>
-
-*options* should contain the following properties:
+<api name="findAndRunTests">
+@function
+  The list of directories is searched for SecurableModules that start
+  with the prefix `test-`.  Each module matching this criteria is
+  expected to export functions that are test cases or a suite of test
+  cases; each is called with a single argument, which is a Test Runner
+  Object.
 
-<table>
-  <tr>
-    <td><code>dirs</code></td>
-    <td>A list of absolute paths representing directories to search
+@param options {object}
+  An object with the following properties:
+  @prop dirs {string}
+    A list of absolute paths representing directories to search
     for tests in.  It's assumed that all of these directories are also
     in the module search path, i.e. any JS files found in them are
     SecurableModules that can be loaded via a call to
-    <code>require()</code>.</td>
-  </tr>
-  <tr>
-    <td><code>onDone</code></td>
-    <td>A function to call when testing is complete.</td>
-  </tr>
-</table>
-
-The list of directories is searched for SecurableModules that start
-with the prefix `test-`.  Each module matching this criteria is
-expected to export functions that are test cases or a suite of test
-cases; each is called with a single argument, which is a Test Runner
-Object.
+    `require()`.
+  @prop onDone {function}
+    A function to call when testing is complete.
+</api>