 # 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


    # ## set
    # - - -
    # TODO: write documentation
    #
    #
    # - - -
    set: (fields) ->
        unless J.util.isPlainObject fields

    @escapeDot: (key) ->
        key.replace(/\./g, '*DOT*').replace(/\$/g, '*DOLLAR*')


    # ## @fromJSONValue
    # - - -
    # Return a new model instance with the fields set to a given JSON.
    # The input is *not* of the form `{$type: ThisModelName, $value: someValue}`.
    # It's just the `someValue` part.
    # - - -
    @fromJSONValue: (jsonValue) ->

        unless J.util.isPlainObject jsonValue
            throw new Meteor.Error 'Must override J.Model.fromJSONValue to decode non-object values'
