 
     # ## typeName
     # - - -
-    # TODO: write documentation
+    # Used by Meteor EJSON.
+    # - - -
+    typeName: ->
+        @modelClass.name
+
+
+    # ## update
+    # - - -
+    # Update the corresponding model document in `@collection`
+    # using MongoDB operators.
     #
-    #
-    # - - -
-    typeName: ->
-        # Used by Meteor EJSON
-        @modelClass.name
-
-
-    # ## update
-    # - - -
-    # TODO: write documentation
-    #
-    #
+    # Calling something like `foo.update(bar: baz)` would replace the entire
+    # Mongo doc, which is basically always a mistake. We almost always
+    # want to call something like `foo.update($set: bar: baz)` instead.
     # - - -
     update: (args...) ->
         unless @alive
             throw new Meteor.Error "Can't call update on dead #{@modelClass.name} instance"
 
         unless J.util.isPlainObject(args[0]) and _.all(key[0] is '$' for key of args[0])
-            # Calling something like .update(foo: bar) would replace the entire
-            # Mongo doc, which is basically always a mistake. We almost always
-            # want to call something like .update($set: foo: bar) instead.
             throw new Meteor.Error "Must use a $ operation for #{@modelClass.name}.update"
 
         @collection.update.bind(@collection, @_id).apply null, args


    # ## save
    # - - -
    # TODO: write documentation
    #
    #
    # - - -
    save: (options = {}, callback) ->
        if _.isFunction(options) and arguments.length is 1
            # Can call save(callback) to use @collection
            # as the collection.
            callback = options
            options = {}


# must be defined before all components.
modelDefinitionQueue = []


# ## J.defineModel (J.dm)
# - - -
# Define a model. The definition may include
# an `_id`, field declarations under `fields`,
# and reactive definitions under `reactives`.
#
# * `@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.
#
# * When a model instance is attached, it reactively receives
# changes from its collection and is immutable
# to the application layer.  
# Note that an attached instance always has an `_id.`
#
# * 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.
# 
#
#     J.dm 'Foo', 'foos',
#         _id: $$.str
#        
#         fields:
#             a:
#                 type: $$.str
#             b:
#                 type: $$.str
#                 include: false
#             c:
#                 type: $$.str
#        
#         reactives:
#             d:
#                 val: ->
#                     @a() + @c()
#             e:
#                 include: true
#                 val: ->
#                     @b() + 1
#             f:
#                 denorm: true
#                 val: ->
#                     $$.Bar.fetch({ baz: 1 }).count()
# - - -
J.dm = J.defineModel = (modelName, collectionName, members = {}, staticMembers = {}) ->
    modelDefinitionQueue.push
        modelName: modelName
