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
)();