How To Document

This section shows the guidelines to create the osgjs API Documentation. Descriptions should be written in Markdown format.

This project is documented using documentation.js. It is a documentation generation system based in JSDoc syntax. For a complete description of the language visit @use JSDoc.

Installation

To start adding documentation to this project you only need to install documentation.js npm package:

npm install -g documentation

It's supposed that you previously did a $npm install.

Generating the documentation

To generate the docs there exists a grunt task:

grunt docs

IDE integration

SublimeText

If you're using the SublimeText editor you can install PackageControl and add the DocBlockr plugin to write documentation comments easily.

Emacs

There exists also some integration for Emacs, for example https://github.com/mooz/js-doc

Documenting a namespace

Each folder (osg, osgAnimation, osgDB, osgGA, osgShader,...) corresponds to a namespace. So, use @namespace tag to document the namespace in the file where the module is declared.

This way allows to enclose the classes in groups.

 /** @namespace osgAnimation * /

Documenting a class

/**
 * Manage BlendColor attribute
 * @class BlendColor ( class name is not really needed as it is parsed from the class name below)
 * @memberof osg
 * @extends StateAttribute
 * /

Define the class with the tag @class.

Use always @memberof to enclose the class in the group/module it belongs. Be aware of the letter case.

Use @extends to indicate inheritance. Use @property to specify each property of the class.

Documenting a method

 /**
 * Set the dimension mask.(we put here method description)
 * @method
 * @memberof osgUtil.PolytopeIntersector
 * @param  {mask} here a few words about param
 * @return {value} here a few words about the return value
 * /

Define always method with the tag @method.

Use always @memberof to enclose the method in the class it belongs. Be aware of the letter case.

Use @param to document the function's parameters.

Use @return to document the return value of a function.

How to include examples

Use the tag @example to provide an example of how to use a documented item.

/**
* @example
* //How to read a node and add it to the scene
*  osgDB.readNodeURL( '../media/models/material-test/file.osgjs' ).then( function ( node ) {
*    root.addChild( node );
*    viewer.getManipulator().computeHomePosition();
* } );
* /