oxjs/readme/html/OxDoc.html

<script>
    Ox.tmp = {
        dialog: function(id) {
            var source = Ox.decodeHTMLEntities(Ox.stripTags(
                    $('#' + id).html()
                    .replace(/&nbsp;/g, ' ')
                    .replace(/<br>/g, '\n')
                )),
                doc = Ox.doc(source);
            Ox.Dialog({
                closeButton: true,
                content: Ox.TabPanel({
                    content: {
                        source: Ox.SyntaxHighlighter({
                            showLineNumbers: true,
                            source: source
                        }),
                        doc: Ox.TreeList({
                            data: doc,
                            width: 640
                        }).css({height: 360}),
                        docpage: Ox.DocPage({
                            item: doc[0]
                        })
                    },
                    tabs: [
                        {id: 'source', title: 'source'},
                        {id: 'doc', title: 'doc=Ox.doc(source)'},
                        {id: 'docpage', title: 'Ox.DocPage(doc[0])'}
                    ]
                }),
                height: 360,
                title: 'OxDoc',
                width: 640
            }).open();
        }
    }
</script>
<h1>Ox.doc - A JavaScript Documentation Language</h1>

<p>At its core, Ox.doc is list of lines like this:</p>
<pre class="code">//@ name &lt;type&gt; summary</pre>
<p>...</p>
<pre class="code">/*@
name &lt;type&gt; summary
    Longer description
    that may contain HTML.
@*/
</pre>

<p>If you are documenting an object with properties, these lines can be nested:</p>
<pre class="code">/*@
My.team &lt;object&gt; Some sports team
    name &lt;string&gt; The team's name
    lastMatch &lt;object&gt; The most recent result
        for &lt;number&gt; Goals for
        against &lt;number&gt; Goals against
    won &lt;boolean&gt; If true, last match was a win
@*/</pre>

<p>The same goes for functions and events:</p>
<pre class="code">/*@
My.readURL &lt;function&gt; Reads data from a remote URL
    (url, callback) -&gt; &lt;o&gt; Request handler
        cancel &lt;function&gt; The handler's only property. Takes no arguments. Cancels the request.
    url &lt;string&gt; Remote URL
    callback &lt;function&gt; Callback function
        result &lt;object&gt; Result object
            status &lt;number&gt; HTTP status code
            data &lt;string&gt; Data read from URL, or empty string
    stalled &lt;event&gt; Fires when the connection is stalled
        reason &lt;string&gt; Potential cause of the network problem
@*/</pre>


<p></p>

<pre class="code">/*@
foo &lt;o&gt; Demo object
    array     &lt;a&gt; An array (and we don't care about the type of its elements)
    boolean   &lt;b&gt; True or false
    date      &lt;d&gt; Date object
    element   &lt;e&gt; DOM element
    function  &lt;f&gt; A function
    number    &lt;n&gt; A number
    object    &lt;o&gt; An object
    regexp    &lt;r&gt; Regular Expression
    string    &lt;s&gt; A string
    undefined &lt;u&gt; 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 &lt;*&gt; anything
    event     &lt;!&gt; A custom event
    example1  &lt;[n]|u&gt; An array of numbers, or undefined
    example2  &lt;s|'foo'&gt; A string, default 'foo'
@*/
</pre>

<p>foo bar</p>

<pre class="code" id="foo">//@ My.TYPES &lt;number&gt; Request timeout, in seconds
My.REQUEST_TIMEOUT = 60;</pre>
<a href="javascript:Ox.tmp.dialog('foo')">try it out</a>

<p>foo bar</p>

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

<p>foo bar</p>

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


<p>foo bar</p>

<pre class="code">/*@
My.Request &lt;o&gt; Remote request utility
@*/
My.Request = (function()
    // ...
    r
)();</pre>