     @connected(token, silent: true) if token
     @unsaved = []
 
-  pluginInit: () ->
+  # Internal: Called by the Annotator after the intance has been created and 
+  # @annotator property has been attached. Sets up initial plugin state.
+  #
+  # Returns nothing.
+  pluginInit: ->
     jQuery("body").append @view.render()
-    @lookupBook().done
-
+    @lookupBook()
+
+  # Public: Fetches the book resource from the Readmill API and updates the
+  # view when complete. This method is usually called as part of the plugin
+  # setup.
+  #
+  # The method also attaches a "promise" property to @book which can be used
+  # to determine if the book is loaded.
+  #
+  # Examples
+  #
+  #   readmill.lookupBook()
+  #
+  # Returns a jQuery.Deferred() promise.
   lookupBook: ->
-    return @book.deferred if @book.deferred
-
-    @book.deferred = if @book.id
+    return @book.promise if @book.promise
+
+    @book.promise = if @book.id
       @client.getBook @book.id
     else
       @client.matchBook @book
 
-    @book.deferred.then(@_onBookSuccess, @_onBookError).done =>
+    @book.promise.then(@_onBookSuccess, @_onBookError).done =>
       @view.updateBook @book
 
   lookupReading: ->

# Grab the Delegator class here as it's useful for other Classes.
Annotator.Class = Annotator.__super__.constructor

Annotator.Readmill = class Readmill extends Annotator.Plugin
  @API_ENDPOINT: "http://localhost:8000"

  events:
    "annotationCreated": "_onAnnotationCreated"
    "annotationUpdated": "_onAnnotationUpdated"
    "annotationDeleted": "_onAnnotationDeleted"

  constructor: (options) ->
    super

    # Rather than use CoffeeScript's scope binding for all the event handlers 

    if annotation.highlightUrl
      @client.deleteHighlight(annotation.highlightUrl).error =>
        @error "Unable to update annotation in Readmill"

window.Annotator.Plugin.Readmill = Annotator.Readmill
