Writing Documentation

Writing Inline Documentation

We use the marvelous documentation.js to generate our new docs. This means we can transform JSDoc syntax in function comments to generate content for the docs. This means we have to follow some simple rules to create useful comments that can be parsed.

Table of Contents generated with DocToc

• Use Sublime Text and DocBlockr
• Descriptions
• Categories & Sub Categories
• Functions
  • Function Description
  • Function Parameters
  • Function Paramters Objects
  • Function Return Values
  • Example Code
• Constants
• Variables
• Properties
• Even more Tags?

Use Sublime Text and DocBlockr

To easily write code you should use Sublime Text and the package DocBlockr. It allows to add pre filled JSDoc comments just by typing /** + ENTER before a function.
Then you can walk through all the needed fields by pressing TAB and filling out the infos. Easy like stealing candy from a toddler.

The first paragraph/sentence will be parsed as the description for the function/variable. If you want to write even more infos, add links or make something stand out, you can add HTML tags. To do this you need to use the @description tag though, or your sentence will get cut of at the first tag.

!Dont forget a period at the end of your sentences.

Descriptions

/**
 * This will be parsed as a description.  
 */

The first Strings until the end or the first tag will be used as description for your function or variable.

If you want to use HTML for highlighting something in your description or to add a link you need to use the @description or @desc tags. This also allows to place your description anywhere in the comment block.

/**
 * @constant
 * @description This will be parsed as a description.
 * With multiple lines and <strong>HTML!</strong>.
 */

Categories & Sub Categories

To group things together in the docs we use two specific tags that are not part of the JSDoc definition. @cat for categories and @subcat for sub categories. The currently existing categories are:

Color, Data, Document, Environment, Math, Output, Story, Typography

The sub categories are:

Units, Primitives, Constants, Page, modes, Multi-Getters, Date, JSON, Conversion, String Functions, Input, Attributes, Transformation, Image, Calculation, Trigonometry, Random, Array Functions, HashList, CSV, Type-Check, Misc, Vector

A category is always needed. A sub category is optional. Before introducing a new category you should consider writing an issue. Subcategories can be introduced at will.

Functions

/**
 * A fun function.
 * @method fun
 */
function fun (){
    
}

To declare something as a function we can use the @function, @func or @method tag. Currently the @method tag is used throughout Basil. We can keep it that way.

Function Description

/**
 * This will be parsed as a description.  
 */
function fun(){

}

See the Descriptions section for further infos.

Function Parameters

/**
 * A functiion for more foo.
 * @param  {Number} bar  A number for bar.
 * @param  {String} baz  A String that is baz.
 * @param  {Boolean} boom A Boolean that goes boom.
 * @param  {Array} peng An Array of pengs.
 * @param  {Object} [pow]  A optional pow object for storing things.
 * @param  {Stories} [col] A optional <code>Collection</code> of <code>Story</code> objects.   
 * @param  {Document|Page|Story} whut Some <em>different</em> things. 
 */
function foo(bar, baz, boom, peng, pow, col, whut){
}

If the function has parameters you should add them with the @param tag. After the tag follows the type {Type} of the variable. Use standard JS types or InDesign classes as type. You can have multiple types by seperating them with a |. The first word after the type is the variable name. Never forget it. If you set the name in [] it indicates that this parameter is optional. Then follows the variable description. Start it with a capitalcase word and end it with a period. You also can have HTML tags in there. Of course the parameters should be in the right order.

Function Paramters Objects

/**
 * My fancy object paramter.
 * @param {Object} settings - The description of the object.
 * @param {string} settings.name - The description of the objects properties.
 * @param {string} settings.andwhatnot - and even more description.
 */

function foo(settings){
}

If you need to document properties of objects, like in the example above, you can display them with the . operator. Each key in the object becomes a additional @param section.

Function Return Values

/**
 * A function that does foo.
 * @return {Number} A simple calculation.  
 */
function foo(){
    return 1 * 2;
}

If your function returns something. Then you can add the @return tag.
Warning currently all returns are actually named @returns DocBlockr uses @return we should move to @return for all functions. Can be done with one simple find and replace action per file. After the tag follows the type {Type} in curly brackets. This should be the real type. Not a description. The description of the content should follow afterwards as a text.

Right:

/**
 * A foo function.
 * @return {Array} An array of strings.  
 */
function foo (){
    return ['one', 'two', 'three'];
}

Wrong:

/**
 * A foo function.
 * @return {String[]} An array of strings.  
 */
function foo (){
    return ['one', 'two', 'three'];
}

InDesign has something similar to an Array. A Collection. These should also be of the type of the collection when used as return value (see the example below).

/**
 * A foo function.
 * @return {Stories} A collection of Story objects.  
 */
function foo (){
    return app.documents[0].pages[0].stories;
}

Example Code

/**
 * Simple example of multiplication.
 * @param  {Number} a A number.
 * @param  {Number} b A second number.
 * @example <caption>This is the first example</caption>
 * var val = mult(10, 5);
 * val = val * 2;
 * @example <caption>This is another example.</caption>
 * var val = mult(5, 10);
 * val *= 2;
 * @return {Number} A multiplied number.
 */
function nult (a, b) {
  return a * b;
}

You also can add example code using the @example tag. If you want an additional for the example add it in the first line using the <caption> HTML Tag. All Lines until the next tag will be parsed as part of the example code. New line characters will be inserted as \n.

Constants

/**
 * A FOO value.
 * @constant
 * @type {Number}
 */
var FOO = 1;

Constant values should also be marked as these.

Variables

/**
 * A simple variable.
 * @type {Number}
 * @default 100
 */
var something = 100;

Variables can also be documented. If you add the @default tag, you can pass also a value to the docs.

The @default tag allows you to document the assigned value of a symbol. You can supply this tag with a value yourself or you can allow JSDoc to automatically document the value from the source code -- only possible when the documented symbol is being assigned a single, simple value that is either: a string, a number, a boolean or null.
usejsdoc.org/tags-default.html

Properties

/**
 * An object.
 * @type {Object}
 * @property {String} foo A foo string.
 * @property {Object} baz A baz object.
 * @property {String} baz.bum A String in baz.
 * @property {Boolean} baz.bang A Boolean in baz.
 */
var obj = {
  foo: 'bah',
  baz:{
    bum: 'pow',
    bang: true
  }
};

If documenting a property of an object you can use the @property tag.

Even more Tags?

See the jsdoc.org site. If you think there is something missing - write an issue.