 # this holds the documentation for the message protocol
 exports.documentation = {}
 
-# holds all the tests
-exports.tests = {}
+# holds all the examples: list of expected in/out objects for each message
+exports.examples = {}
 
 API = (obj) ->
+    # obj could be message version 1 or 2!
     exports.api_messages[obj.event] = true
 
 ############################################

# TODO document it, for now just search for "message2" to see examples
message2 = (obj) ->

    mk_descr = (val) ->
        descr = val.descr 
        descr += ' (required)' if val.init == required
        return descr

    init   = _.mapObject(obj.fields, ((val) -> val.init))
    fdescr = _.mapObject(obj.fields, mk_descr)
    exports.documentation[obj.event] =
                                descr : obj.descr ? ''
                                fields: fdescr
    exports.tests[obj.event] = obj.tests

    exports[obj.event] = (opts={}) ->
        if opts.event?
            throw Error("ValueError: must not define 'event' when calling message creation function (opts=#{JSON.stringify(opts)}, obj=#{JSON.stringify(obj)})")
        defaults(opts, init)
    return obj

# messages that can be used by the HTTP api.   {'event':true, ...}


API message2
    event          : 'query'
    desc           : "This queries directly the database (sort of Facebook's GraphQL)"
    fields:
        id:
             init  : undefined
             desc  : 'A unique UUID for the query'
        query:
             init  : required
             desc  : 'The actual query'
        changes:
             init  : undefined
             desc  : ''
        multi_response:
             init  : false
             desc  : ''
        options:
             init  : undefined
             desc  : ''
    examples: [
        [{id: "uuid", query: 'example1-query'},
         {id: "uuid", event: 'query', response: "..."}
        ],
        [{id: "uuid", query: 'example2-query'},
         {id: "uuid", event: 'query', response: "..."}
        ]
    ]

message
