Definition
Provides meta information about the document associated with the annotated element.
Please not that some of the annotation's information found at the type level are inherited to the elements defined in this type. These elements are explicitly documented to reflect this.
The following meta data is provided by this annotation.
Name
The name of the element as it is to be used in the documentation. This allows to specify names that are otherwise impossible due to Java naming rules.
At type level the content may be used as a prefix for all elements of the type.
The name is required to be unique and is not necessarily human readable. The name may be a local name that is only unique within a given context, if this context information is be added by the parser/tool.
This is an identification element.
Space
A document may be associated with a space. While the name is required to be unique within the set of all documents, the title of a document is only unique within its space.
If this information is given at type level, it is inherited to the elements defined in this type (if a value is not provided explicitly on the element level).
This is an identification element.
Audience
Names the intended audience of the document.
If this information is given at type level, it is inherited to the elements defined in this type. Any information provided at the element level is added to the inherited values.
This is an description element.
Short Description
A short description to be used in a tabular index.
At type level the content is applied to the set of properties.
This is an description element.
Summary
A summary with more details than the short description.
At type level the content is applied to the set of properties.
This is an description element.
Notes
Some notes to be added to the documentation of the element.
At type level the notes are added to the notes of the individual elements.
This is an description element.
Sort Key
The optional sort key if a natural ordering on the title or name is not sufficient.
This is an filing element.
Usage
The following examples show how the Document annotation can be used.
@Document(name = "parent", shortDescription = "Parent Short Description.",
notes = { "Parent Note 1", "Parent Note 2" }, space = "parent space",
title = "Parent Title", sortKey = "Parent Sort Key",
summary = "Parent Summary", audience = { "developer", "plugin developer" })
public interface TestProperties {
String inheritAll();
@Document(name = "Child Name 1",
shortDescription = "Child 1 Short Description.",
notes = { "Child 1 Notes" }, space = "Child 1 Space",
title = "Child 1 Title", sortKey = "Child 1 Sort Key",
summary = "Child 1 Summary", audience = "Child 1 Audience")
String oneValue();
@Document(audience = { "Child 2 Audience 1", "Child 2 Audience 2" })
String multipleValues();
}