¶ Edit

X Delete

2344 views

8 years ago

Documenting Code

AppJet will automatically generate documentation for your code using a modified version of JSDoc. This is extremely useful for sharing libraries and code with the AppJet community.

Here we will give an overview of the most common JSDoc features. For a full reference, see The JSDoc Documentation Page.

To view the documentation for any library or app, you can go to the source page and select the "Docs" tab. Or, as a shortcut, just visit docs.app-name.appjet.net. For example, to view the docs for the following example, you can visit docs.lib-example.appjet.net.

Here's an example library using JSDoc tags. See docs.lib-example.appjet.net to view the generated docs.

/* appjet:library */

/**
 * @overview This is an example AppJet library that includes
 * JSDoc-style documentation. <br><br>
 *
 * In particular, it defines the functions someFunction() and 
 * reverseString().
 *
 * For the full capabilities of JSdoc, see 
 * <a href="http://jsdoctoolkit.org/wiki/">jsdoctoolkit.org</a>.
 *
 * @example
var x = "Aaron";
print(reverseString(x)); // prints "noraA"
 */


/**
 * Here is a basic function with no arguments and no return value.
 * <p>Note that you can put <b>HTML</b>
 * <font color=purple>markup</font> inside JSDoc-comments.</p>
 */
function someFunction() {
}

/**
 * This function reverses a string.
 *
 * @param {string} str The string to be reversed
 * @return {string} The reversed string
 */
function reverseString(str) {
    return str.reverse(); // doesn't actually work
}

/**
 * This function calculates the arithmetic mean of three numbers.
 *
 * @param {number} x First of the three numbers
 * @param {number} y Second of the three numbers
 * @param {number} z Third of the three numbers
 * @return {number} The computed value of (x+y+z)/3
 *
 * @example
var result = mean3(1,2,3);
print(result); // prints "2"
 *
 * @example
// here is another example:
var result = mean3(4,5,6);
print(result); // prints 5
 */
function mean3(x, y, z) {
    return (x + y + z) / 3;
}

function _ignored() {
    // this function is hidden from auto-documentation
    // because it begins with an underscore.
}

/** @ignore */
function alsoIgnored() {
    // this function is also ignored because its doc was given
    // an @ignore tag.
}

// Here are some useful global variables.
// Note that "//"-style comments are not included in
// generated docs.

/**
 * Holds the value of pi.  About 3.14159.
 * @type number
 */
var PI = 3.14159;

/**
 * Holds the secret password.
 * @type string
 */
var PASSWORD = "itsasecret";


/* appjet:server */
print(link("http://docs.lib-example.appjet.net",
    "View the Docs"));
Powered by AppJet on JGate
source
rendered in 0.118s