Script documentation.md

Script documentation

When creating script-includes and other (mostly server-side) scripts try to follow these documentation guidelines. For more information about the tags check: JSDoc

Example

We take our example script from scriptIncludeCC. Documented it should look something like this:

/**
 * [name]
 *
 * [description]
 */
var SomeClass = Class.create();

SomeClass.prototype = Object.extendsObject(AbstractAjaxProcessor, {

	// [optional description]
	type: "SomeClass",

	/**
	 * [description]
	 * [input params]
	 * [input params]
	 * [input params]
	 * [input params]
	 * [returns]
	 */
	getSomething: function(id,name,count,user) {

		// [optional description per line or code block]
		if (user === undefined) {
			user = max;
			max = 0;
		}

		// Some other code
		...

		return data;
	}
}

Example documented

So adding "actual" documentation it will look something like this

/**
 * SomeClass
 *
 * The class that helps you do some classy things!
 */
var SomeClass = Class.create();

SomeClass.prototype = Object.extendsObject(AbstractAjaxProcessor, {

	type: "SomeClass",

	/**
	 * Get some data based on some example params
	 * @param {sys_id} id             - The sys_id of a record
	 * @param {string} name           - The name of the collection
	 * @param {number} [max]          - (optional) The maximum number of records to retrieve
	 * @param {Object} user           - A user provided along with the request
	 * @param {number} user.age       - The user's age
	 * @param {string} user.firstName - The user's first name
	 * @param {string} user.lastName  - The user's last/sur name
	 * @returns {Object}              - An object containing all records complying with the input params
	 */
	getSomething: function(id,name,max,user) {

		// Allow for max to be optional
		if (user === undefined) {

			// Max now contains the user info so set the user var with it
			user = max;

			// Set max to be 0
			max = 0;
		}

		// Some other code
		...

		// Return the data
		return data;
	}
});