# OxDoc — A JavaScript Documentation Language

`OxDoc` is a new format for JavaScript documentation. It was developed for and is used throughout `OxJS`, which provides a parser and a browser for it.

`OxDoc` itself isn't formally documented yet, but you may want to take a look at the extensive tutorial. The sample below should give you a rough first idea.

For now, `OxDoc` should be considered a proposal, and this introduction is, above all, a request for comments.

    //@ Section Name
    this.My = {};
    //@ My.foo <number> One-line summary, with *some* `markdown`
    My.foo = 23;
    /*@
    My.bar <object> Summary
        Optional multi-line description, with *some* `markdown`.
        property <object> A property of `My.bar`
            Description of `property`.
            foo <number> A number
            bar <[string]> An array of strings
        method <function> A method of `My.bar`
            (foo[, bar], callback) -> <undefined> Return value
            foo <number|string> Argument, number or string
            bar <boolean|false> Optional argument, default is `false`
            callback <function> Callback function
                arg <boolean> Argument
        baz <event> An event triggered by `My.bar`
            x <number> Event property
            y <number> Event property
        # This is a comment. Below are inline tests. The last one is asynchronous.
        > My.bar.property.foo < 1
        true
        > My.bar.property.bar.join('')
        'string'
        > My.bar.method(1, function(arg) { Ox.test(arg, true); })
        undefined
    */
    My.bar = {
        property: {
            foo: Math.random(),
            bar: 'string'.split('')
        },
        method: function(foo, bar, callback) {
            if (arguments.length == 2) {
                callback = bar;
                bar = false;
            }
            if (bar) {
                // trigger baz event
            }
            setTimeout(function() {
                callback(!!foo);
            });
        }
    };