# Ox.doc - A JavaScript Documentation Language

At its core, Ox.doc is list of lines like this:

    //@ name <type> summary

...

    /*@
    name <type> summary
        Longer description
        that may contain HTML.
    @*/

If you are documenting an object with properties, these lines can be nested:

    /*@
    My.team <object> Some sports team
        name <string> The team's name
        lastMatch <object> The most recent result
            for <number> Goals for
            against <number> Goals against
        won <boolean> If true, last match was a win
    @*/

The same goes for functions and events:

    /*@
    My.readURL <function> Reads data from a remote URL
        (url, callback) -> <o> Request handler
            cancel <function> The handler's only property. Takes no arguments. Cancels the request.
        url <string> Remote URL
        callback <function> Callback function
            result <object> Result object
                status <number> HTTP status code
                data <string> Data read from URL, or empty string
        stalled <event> Fires when the connection is stalled
            reason <string> Potential cause of the network problem
    @*/

    /*@
    foo <o> Demo object
        array     <a> An array (and we don't care about the type of its elements)
        boolean   <b> True or false
        date      <d> Date object
        element   <e> DOM element
        function  <f> A function
        number    <n> A number
        object    <o> An object
        regexp    <r> Regular Expression
        string    <s> A string
        undefined <u> undefined
            Makes most sense for the result of a function that doesn't return,
            or as the last of multiple types, to indicate a property may be missing
        any_value <*> anything
        event     <!> A custom event
        example1  <[n]|u> An array of numbers, or undefined
        example2  <s|'foo'> A string, default 'foo'
    @*/

foo bar

    //@ My.TYPES <number> Request timeout, in seconds
    My.REQUEST_TIMEOUT = 60;

try it out

foo bar

    /*@
    My.getProtocol <function> Returns the protocol part of a URL
        (url) -> <string> Protocol, like "https", otherwise ""
        url <string> Just some URL
    @*/
    My.getProtocol = function(url) {
        var match = url.match(/^(.+):\/\//);
        return match ? match[1] : '';
    };

foo bar

    /*@
    My.readURL <f> Reads data from a remote URL
        (url, callback) -> <o> Request handler
        (url, options, callback) -> <o> Request handler
            cancel <f> Function to cancel the request
        url <s> Remote URL
        options <o> Optional config object
            timeout <n|60> Timeout in seconds
            type <s|'GET'> Request type ('GET', 'POST', 'PUT' or 'DELETE')
        callback <f> Callback function
            result <o> Result object
                status <n> HTTP status code
                data <s> Data read from URL, or empty string
    @*/
    My.readURL = function(url, options, callback) {
        if (arguments.length == 2) {
            callback = options;
            options = {timeout: 60, type: 'GET'};
        }
    };

try it out

foo bar

    /*@
    My.Request <o> Remote request utility
    @*/
    My.Request = (function()
        // ...
        r
    )();