Restructure docs

It's still not perfect but, probably good enough for now

docs/api-adding-tests.md

@@ -0,0 +1,68 @@
+These `CanaryTest` methods are needed to write tests that can be run with Canary.
+
+Tests and test groups can optionally be assigned names. It is strongly recommended that test names always be provided, since descriptive names will make it easier to understand where errors occur, when they occur.
+
+# test
+
+Add an individual test. Tests are added to test groups. This results in a test tree, or hierarchy, where the test created in this way is a child of the test group it was added to.
+
+**Arguments:** `({string} name, {function} body)` _or_ `({function} body)`
+
+If the body function returns a `Promise`, then when the test is run Canary will wait to see if the promise is resolved or rejected before completing the test and progressing to the next one. (A resolved promise indicates that this part of the test ran without errors and a rejected promise is treated the same as an unhandled thrown error.)
+
+When the body function is called, both `this` and the first argument will refer to the test to which the function belongs.
+
+**Returns:** The newly-created `CanaryTest` instance.
+
+**Examples:**
+
+``` js
+canary.test("Example test", function(){
+    assert(2 + 2 === 4);
+});
+```
+
+``` js
+canary.group("Example test group", function(){
+    this.test("Example test", function(){
+        assert(1 < 3);
+    });
+});
+```
+
+``` js
+canary.test("Example asynchronous test", async function(){
+    const result = await someAsyncFunction();
+    assert(result === 10);
+});
+```
+
+# group
+
+Add a test group. A test group is a special kind of test that may have child tests and callbacks such as `onBegin` and `onEnd`, but must not itself contain test logic.
+
+**Arguments:** `({string} name, {function} body)` _or_ `({function} body)`
+
+The body function should be synchronous. If it happens to return a `Promise` then, unlike a test instantiated with the `test` method, Canary will not wait for that promise to be resolved or rejected.
+
+When the body function is called, both `this` and the first argument will refer to the test to which the function belongs.
+
+**Returns:** The newly-created `CanaryTest` instance.
+
+**Examples:**
+
+``` js
+canary.group("Example test group", function(){
+    this.group("First child group", function(){
+        this.test("First example test", function(){
+            assert("hello" === "hello");
+        });
+    });
+    this.group("Second child group", function(){
+        this.test("Second example test", function(){
+            assert("world" === "world");
+        });
+    });
+});
+```
+

docs/api-advanced-usage.md

@@ -0,0 +1,191 @@
+These `CanaryTest` class methods are for those who need more complex or customized behavior from Canary. They are not relevant to the majority of users.
+
+# silent
+
+Set a test and all its children to run silently. This means that they will not output any log messages.
+
+The `log` method of a `CanaryTest` instance can be used to log a message only if the test has not been set to run silently.
+
+Note that when the `concise` flag of the `doReport` function is set, it will cause all tests to run silently.
+
+**Examples:**
+
+``` js
+canary.test("Example silent test", function(){
+    this.silent();
+});
+```
+
+# verbose
+
+Set a test and all its children to run verbosely. This means they will output even more detailed logs than usual.
+
+The `logVerbose` method of a `CanaryTest` instance can be used to log a message only when the test is set to run verbosely.
+
+Note that when the `verbose` flag of the `doReport` function is set, it will cause all tests to run verbosely that were not otherwise set to run silently.
+
+**Examples:**
+
+``` js
+canary.test("Example verbose test", function(){
+    this.verbose();
+});
+```
+
+# shouldSkip
+
+Check whether any flags have been set that will cause this test to be skipped, such as by using the `todo` or `ignore` methods.
+
+**Returns:** `true` is marked to be skipped `false` when it is not so marked.
+
+# unignore
+
+Un-ignore a test that was previously marked as being ignored.
+
+**Examples:**
+
+``` js
+const someTest = canary.test("Example test", function(){
+    this.ignore();
+});
+someTest.unignore(); // Nevermind!
+```
+
+# getTitle
+
+Get an identifying title for this test. A test's title is its name, preceded by the name of its parent test, preceded by its parent's name, and so on.
+
+**Returns:** A string, representing a title that can be used to identify this test.
+
+# getName
+
+Get the name provided for this test.
+
+**Returns:** The test's name as a string.
+
+# hasTag
+
+Determine whether this test has a certain tag or not.
+
+**Arguments:** `({string} tag)`
+
+**Returns:** `true` when the test has the tag and `false` when it does not.
+
+# getTags
+
+Get a list of tags that have been added to this test.
+
+**Returns:** An array of tags.
+
+# getTestTotal
+
+Recursively get the number of `CanaryTest` instances in a test tree.
+
+Note that if this method is called for a test group, and the group has not already been expanded, then this method will cause it to be expanded. (As though the `expandGroups` method was called.)
+
+**Returns:** The total number of tests in this test tree.
+
+# getStatusString
+
+Get a string representing the status of this test.
+
+**Returns:** `"skipped"` if the test was marked as skipped or was never attempted, `"passed"` if the test completed successfully, or `"failed"` if the test was unsuccessful.
+
+# durationSeconds
+
+Get the length of time taken to run this test, in seconds.
+
+**Returns:** The number of seconds it took to run the test, or `undefined` if the test has not yet been completed.
+
+# durationMilliseconds
+
+Get the length of time taken to run this test, in milliseconds.
+
+**Returns:** The number of milliseconds it took to run the test, or `undefined` if the test has not yet been completed.
+
+# addError
+
+Add an error to the test's list of recorded errors.
+
+The method requires an Error object and optionally accepts another argument indicating the test or callback where the error occurred.
+
+**Arguments:** `({Error} error, {CanaryTest|CanaryTestCalback} location)`
+
+**Returns:** The newly-created `CanaryTestError` instance.
+
+# abort
+
+Abort the test and mark it as failed.
+
+The method optionally accepts information about the error that resulted in the test being aborted. The first argument, if provided, must be an Error object, and the second argument can be used to indicate the test or callback where the error occured. (This is the same as with the `error` method.)
+
+**Arguments:** `({Error} error, {CanaryTest|CanaryTestCalback} location)`
+
+# anyErrors
+
+Get whether any errors were encountered while running this test.
+
+**Returns:** `true` when the test has recorded any errors and `false` when it has not.
+
+# noErrors
+
+Get whether this test was run without encountering any errors.
+
+**Returns:** `false` when the test has recorded any errors and `true` when it has not.
+
+# getErrors
+
+Get a list of errors that were encountered while attempting this test, if any.
+
+**Returns:** An array of `CanaryTestError` objects encountered while running this test.
+
+# addTest
+
+Add a child test to a test group.
+
+Note that if the test was previously added to another test group, it will be removed from that group as it is added to the new group.
+
+**Arguments:** `({CanaryTest} test)`
+
+# removeTest
+
+Remove a child test from a parent group.
+
+**Arguments:** `({CanaryTest} test)`
+
+**Returns:** `true` if the test was in fact a child and was removed and `false` if it was not.
+
+# orphan
+
+Remove a test from its parent group.
+
+**Returns:** `true` if the test did in fact have a parent and was orphaned and `false` if it did not.
+
+# getParent
+
+Get the `CanaryTest` instance which is the parent of this one.
+
+**Returns:** The `CanaryTest` instance to which this test has been added, or `undefined` if the test does not have a parent.
+
+# getChildren
+
+Get a list of the tests that are children of this test group.
+
+**Returns:** An array of `CanaryTest` instances which are children of this test group.
+
+# applyFilter
+
+Applies a filter function recursively to a test group and all of its children. Tests for which no ancestors or descendants satisfy the filter will be marked, then skipped when tests are run.
+
+This method is leveraged by `doReport` in order to enforce the filtering criteria that are passed to it.
+
+**Arguments:** `({function} filter)`
+
+**Returns:** `true` if this test or any of its descendants satisfied the filter and `false` if not.
+
+# expandGroups
+
+Recursively run all the body functions assigned to test groups, but not to ordinary tests. This has the effect of elaborating the structure of the test tree without actually running tests.
+
+Group expansion is put off until tests are actually needed in order to make the startup performance impact of including tests in an application source file close to nonexistent, even in the case of testing code errors that could potentially cause hangups, since extremely little work is done at the time of declaration.
+

docs/api-callback-class.md

@@ -0,0 +1,20 @@
+The `CanaryTestCallback` class is used to represent callbacks added to a test using methods such as `onBegin` and `onEnd`. It has a constructor and no methods.
+
+# getOwner
+
+Get the test object to which this callback belongs.
+
+**Returns:** The `CanaryTest` instance to which this callback was added.
+
+# getName
+
+Get a string naming this callback.
+
+**Returns:** A string representing the name of this callback.
+
+# getTitle
+
+Get a string containing an identifying title for this callback.
+
+**Returns:** A string representing the title of this callback.
+

docs/api-error-class.md

@@ -0,0 +1,31 @@
+The `CanaryTestError` class is used to record errors encountered while attempting tests using Canary.
+
+# stack
+
+A property to get the stack trace attribute of the error object that this `CanaryTestError` instance was instantiated with, provided such an attribute exists.
+
+**Value:** A stack trace, or `undefined` if none was found.
+
+# message
+
+A property to get the message attribute of the error object that this `CanaryTestError` instance was instantiated with, provided such an attribute exists.
+
+**Value:** An error message, or `undefined` if none was found.
+
+# getLocationName
+
+Get the name of the test or callback where this error was encountered. The name is a short string that can be used to help identify a test or a callback.
+
+**Returns:** A string giving the name of the location where the error occurred, or `undefined` if the location wasn't known.
+
+# getLocationTitle
+
+Get the title of the test or callback where this error was encountered. The title is a long string that can be used to uniquely identify a test or a callback.
+
+**Returns:** A string giving the title of the location where the error occurred, or `undefined` if the location wasn't known.
+
+# getLine
+
+Get the line of the error's stack trace indicating where in the source the error occurred.
+
+**Returns:** A string indicating on what line and in what file the error occurred, or `undefined` if the information couldn't be found.