 
     # ## set
     # - - -
-    # TODO: write documentation
+    # Set the fields of a model instance.
+    # This method takes an dictionary of
+    # field names and values.
     #
-    #
+    #     foo.set
+    #       bar: 1
+    #       baz: 2
     # - - -
     set: (fields) ->
         unless J.util.isPlainObject fields

J._defineModel = (modelName, collectionName, members = {}, staticMembers = {}) ->
    modelConstructor = (initFields = {}, @collection = @modelClass.collection) ->
        @_id = initFields._id ? null

        # @collection is the collection that was queried
        # to obtain this instance, or the original attached
        # clone-ancestor of this instance, or just the
        # default place we're going to be inserting/saving to.

        # If true, this instance reactively receives
        # changes from its collection and is immutable
        # to the application layer.
        # Note that an attached instance always has an _id.
        @attached = false

        # Attached instances die when the collection
        # they came from no longer contains their ID.
        # They never come back to life, but a new
        # attached instance with the same ID may
        # eventually replace them in the collection.
        # Detached instances dies when their creator
        # computation dies, if there is one.
        @alive = true
        if Tracker.active then Tracker.onInvalidate =>
            @alive = false


    # ## remove
    # - - -
    # Remove a model document from its collection.
    # - - -
    remove: (callback) ->
        unless @alive
