Definition
A category is a keyword or term that helps to categorize elements. The annotated element may be assigned to zero or more categories.
Categories are organized hierarchically. This organization is not reflected in the annotation. The annotations simply identify the categories by their name.
Annotations found at the type level (i.e. a Java class) are inherited to the elements defined in this type.
This is a filing element.
Usage
The following examples show how the DocCategory annotation can be used.
The examples show the category names as string literals. Please consider using constants that define these values. This way it is easier to ensure that the categories are correctly spelled and also may be changed later more easily.
Annotate an Element
The annotation is provided at element level and associates the given category to that element only.
public interface ExampleInterface {
@DocCategory("sample-category")
String element();
}
The category sample-category is assigned to the Element element.
Multiple Categories allowed
The annotation allows to reference a collection of categories.
public interface ExampleInterface {
@DocCategory({ "sample-category one", "sample-category two", "sample-category three" })
String element();
}
The categories sample-category one, sample-category two, and sample-category three are assigned to the Element element.
Inheritance to Elements
Categories specified at type level will be inherited to the elements.
@DocCategory("parent-category")
public interface TestProperties
{
String inheritAll();
@DocCategory({ "sample-category one" })
String oneValue();
@DocCategory({ "sample-category one", "sample-category two", "sample-category three" })
String multipleValues();
}
The element inheritAll is associated with the category parent-category, the element oneValue is associated with parent-category and sample-category one and the element multipleValues is associated with four categories (the one provided by the category at type level and its own three categories).