categories.md

@category tag

Overview

To create documentation which is generated by category, instead of only by class, you can use the @category tag. You can mark a class as belonging to a certain category by using the @category tag. Subcategories can also be used, simply use the / character to separate the levels like/this.

Usage

Before assigning classes to categories, you need to create a JSON file in which you define the categories:

{
    "category" : {
        "displayName" : "Main-level category"
    },
    "category/subcategory" : {
        "displayName" : "A subcategory of 'category'"
    }
}

You need to tell JSdoc where you stored your file by appending a 'categoryfile' property to your conf.json file. If you don't use a conf.json file, you can append it to JSdoc's conf.json.EXAMPLE file (the example file is interpreted when no other config is specified).

    "categoryfile" : "path/to/categoryfile.json"

Now you can use the @category tag to mark which classes belong to which category.

Syntax

@category [category]

Simply specify the category the class belongs to as the category tag's only argument.

Warnings

When you specify a category to a tag, which has not been defined in your category file, JSdoc will throw an exception and documentation will not be generated. Also when the category file can't be find, documentation generation will be halted.

This is to ensure that typos in the category tag don't instantly ruin your documentation.