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