How To Document

This section shows the guidelines to create the PointCloudViz Project 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

Also, you can generate only the documentation of each library executing grunt docs-core, grunt docs-map or grunt docs-ui.

IDE integration

SublimeText

If you're using the SublimeText editor you can install [PackageControl (https://packagecontrol.io/installation) 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 fwe 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
• //Who 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();
• } );
• /