Create API documentation for some of Annotator core

This commit reformats the documentation for some of the key pieces of
Annotator, and generates API documentation from those files.

doc/api/annotator.rst

@@ -0,0 +1,48 @@
+.. default-domain: js
+
+annotator package
+=================
+
+..  class:: annotator.Annotator(element[, options])
+
+    Annotator represents a reasonable default annotator configuration,
+    providing a default set of plugins and a user interface.
+
+    NOTE: If the Annotator is not supported by the current browser it will
+    not perform any setup and simply return a basic object. This allows
+    plugins to still be loaded but will not function as expected. It is
+    reccomended to call Annotator.supported() before creating the instance or
+    using the Unsupported plugin which will notify users that the Annotator
+    will not work.
+
+    **Examples**:
+
+    ::
+    
+        var app = new annotator.Annotator(document.body);
+    
+    :param Element element: DOM Element to attach to.
+    :param Object options: Configuration options.
+
+
+..  function:: annotator.Annotator.prototype.destroy()
+
+    Destroy the current Annotator instance, unbinding all events and
+    disposing of all relevant elements.
+
+
+..  function:: annotator.supported([details=false, scope=window])
+
+    Examines `scope` (by default the global window object) to determine if
+    Annotator can be used in this environment.
+
+    :returns Boolean:
+      Whether Annotator can be used in `scope`, if `details` is
+      false.
+    :returns Object:
+      If `details` is true. Properties:
+
+      - `supported`: Boolean, whether Annotator can be used in `scope`.
+      - `details`: Array of String reasons why Annotator cannot be used.
+
+

doc/api/authorizer.rst

@@ -0,0 +1,50 @@
+.. default-domain: js
+
+annotator.authorizer package
+============================
+
+..  class:: annotator.authorizer.DefaultAuthorizer([options])
+
+    Default authorizer
+
+    :param Object options:
+      Configuration options.
+
+      - `userId`: Custom function mapping an identity to a userId.
+
+
+..  function:: annotator.authorizer.DefaultAuthorizer.prototype.permits(action, annotation, identity)
+
+    Determines whether the user identified by identity is permitted to perform
+    the specified action on the given annotation.
+
+    If the annotation has a "permissions" object property, then actions will be
+    permitted if either of the following are true:
+
+      a) annotation.permissions[action] is undefined or null,
+      b) annotation.permissions[action] is an Array containing the userId of the
+         passed identity.
+
+    If the annotation has a "user" property, then actions will be permitted only
+    if the userId of identity matches this "user" property.
+
+    If the annotation has neither a "permissions" property nor a "user" property,
+    then all actions will be permitted.
+
+    :param String action: The action the user wishes to perform
+    :param Object annotation:
+    :param identity: The identity of the user
+
+    :returns Boolean: Whether the action is permitted
+
+
+..  function:: annotator.authorizer.DefaultAuthorizer.prototype.userId(identity)
+
+    A function for mapping an identity to a primitive userId. This default
+    implementation simply returns the identity, and can be used with identities
+    that are primitives (strings, integers).
+
+    :param identity: A user identity.
+    :returns: The userId of the passed identity.
+
+

doc/api/core.rst

@@ -0,0 +1,106 @@
+.. default-domain: js
+
+annotator.core package
+======================
+
+..  class:: annotator.core.Annotator()
+
+    Annotator is the coordination point for all annotation functionality. On
+    its own it provides only the necessary code for coordinating the lifecycle of
+    annotation objects. It requires at least a storage plugin to be useful.
+
+
+..  function:: annotator.core.Annotator.prototype.addPlugin(plugin)
+
+    Register a plugin
+
+    **Examples**:
+
+    ::
+    
+        function creationNotifier(registry) {
+            return {
+                onAnnotationCreated: function (ann) {
+                    console.log("annotationCreated", ann);
+                }
+            }
+        }
+    
+        annotator
+          .addPlugin(annotator.plugin.Tags)
+          .addPlugin(creationNotifier)
+    
+    
+    :param plugin:
+      A plugin to instantiate. A plugin is a function that accepts a Registry
+      object for the current Annotator and returns a plugin object. A plugin
+      object may define function properties wi
+    :returns: The Annotator instance, to allow chained method calls.
+
+
+..  function:: annotator.core.Annotator.prototype.destroy()
+
+    Destroy the current instance
+
+    Destroys all remnants of the current AnnotatorBase instance by calling the
+    destroy method, if it exists, on each plugin object.
+
+    :returns Promise: Resolved when all plugin destroy hooks are completed.
+
+
+..  function:: annotator.core.Annotator.prototype.runHook(name[, args])
+
+    Run the named hook with the provided arguments
+
+    :returns Promise: Resolved when all over the hook handlers are complete.
+
+
+..  function:: annotator.core.Annotator.prototype.setAuthorizer(authorizerFunc)
+
+    Set the authorizer implementation
+
+    :param Function authorizerFunc:
+      A function returning an authorizer component. An authorizer component must
+      implement the Authorizer interface.
+
+    :returns: The Annotator instance, to allow chained method calls.
+
+
+..  function:: annotator.core.Annotator.prototype.setIdentifier(identifierFunc)
+
+    Set the identifier implementation
+
+    :param Function identifierFunc:
+      A function returning an identifier component. An identifier component must
+      implement the Identifier interface.
+
+    :returns: The Annotator instance, to allow chained method calls.
+
+
+..  function:: annotator.core.Annotator.prototype.setNotifier(notifierFunc)
+
+    Set the notifier implementation
+
+    :param Function notifierFunc:
+      A function returning a notifier component. A notifier component must
+      implement the Notifier interface.
+
+    :returns: The Annotator instance, to allow chained method calls.
+
+
+..  function:: annotator.core.Annotator.prototype.setStorage(storageFunc)
+
+    Set the storage implementation
+
+    :param Function storageFunc:
+      A function returning a storage component. A storage component must
+      implement the Storage interface.
+
+    :returns: The Annotator instance, to allow chained method calls.
+
+
+..  function:: annotator.core.Annotator.extend(object)
+
+    Create a new object which inherits from the Annotator class.
+
+

doc/api/identifier.rst

@@ -0,0 +1,13 @@
+.. default-domain: js
+
+annotator.identifier package
+============================
+
+..  function:: annotator.identifier.Default(identity)
+
+    Default identifier implementation.
+
+    :param identity: The identity to report as the current user.
+    :returns: A function returning an identifier object.
+
+

doc/api/index.rst

@@ -0,0 +1,12 @@
+API documentation
+=================
+
+.. toctree::
+   :maxdepth: 2
+
+   annotator
+   core
+   storage
+   authorizer
+   identifier
+   notifier

doc/api/notifier.rst

@@ -0,0 +1,23 @@
+.. default-domain: js
+
+annotator.notifier package
+==========================
+
+..  class:: annotator.notifier.BannerNotifier(message[, severity=notifier.INFO])
+
+    BannerNotifier is simple notifier system that can be used to display
+    information, warnings and errors to the user.
+
+    :param String message: The notice message text.
+    :param severity:
+       The severity of the notice (one of `notifier.INFO`, `notifier.SUCCESS`, or
+       `notifier.ERROR`)
+
+
+..  function:: annotator.notifier.BannerNotifier.prototype.close()
+
+    Close the notifier.
+
+    :returns: The notifier instance.
+
+