documenting

This guide walks you through adding the right tags to your source or markdown files to create documentation useful to your users.

Every markdown file or comment block like /** */ gets turned into a docObject. Those docObjects are used to render templates to generate the output html.

Tags like @function within a markdown file or comment block add or change properties on the docObject. Understanding the tags behavior is the key to making useful documentation.

Types

A docObject's most important tag is the one that determines its type. The following tags are the type tags and what they document:

• @module - A module's export value.
• @typedef - Defines a custom type.
• @page - A page of information.
• @function - A JavaScript function.
• @static - Creates a placeholder for static properties on a constructor.
• @prototype - Creates a placeholder for prototype properties on a constructor.
• @property - Creates a property value on an object.

A module and typedef tag can document other types like a function. For example, use @module when something is both module and a function.

Structuring your documentation

DocumentJS is very flexible about how your modules get organized in the sidebar and how they link to each other. The following describes useful patterns for different types of projects:

• Multi module projects that use a module loader.

Multi module projects that use a module loader

This section describe how best to document a project or application that has many individual modules that you want documented.

For this scenario, it's common to use the @module tag. It can be used to document modules that return:

• A single function. Ex: @module {function} module/name
• An object with properties. Ex: @module {{}} module/name
• A single constructor function. Ex: @module {function():module/name} module/name

Here's an example multi-module project and its generated docs. It consists of:

• An overview page with a grouping for modules and guides.
• An example of a constructor function.
• An example typedef used by the constructor function to document the constructor function's arguments.
• An example function module.
• An example object module.

Linking

You can link to documentation pages by their name like [NAME TITLE?]. For example, a function like:

@function project.math.add

Can be linked to like [project.math.add] in description or body text. This will create a link like:

<a href="project.math.add.html">project.math.add</a>

A link title can be provided with a space after the docObject name. For example [project.math.add add numbers] creates a link like:

<a href="project.math.add.html">add numbers</a>

A title can be provided for all types. For example, you can include a @function title like:

@function project.math.add add

If a title is provided with the type, but not in a link, the type's title will be used. For example: [project.math.add] with the previous function will create:

<a href="project.math.add.html">add</a>

Custom Tags

You can supply custom tags that modify docObjects. By default any tag that is not matched follows the @_default tag rules. This, combined with custom templates and helpers is usually enough for adding and showing additional information.

For richer behavior, siteConfig supports a tags property that points to a module that specifies which tags will be used to process files.