Documenting Code

Please do not save test edits. If you want to experiment, please use the sandbox.

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. 
	 *
	 * 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.
	 * Note that you can put HTML
	 * markup inside JSDoc-comments.
	 */
	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"));