How to Annotate Extension Classes
Class
To make a class available to this documentation add a @containsExtensions
tag to the class' javadoc.
/** * @author me * @containsExtensions */ class MyExtensionsClass { [...] }
Classification
It is possible to group different extension classes together, for example, all of Ptolemy's
extensions belong to the same logic block. To create such a classification just add an
identifier to the @containsExtensions
tag. The default classification is
default.
/** * @containsExtensions ptolemy */ class AnnotationExtensions { [...] }
Method
All methods of an extension class are grouped by the class of their first parameter. For each class a section is created within the documentation that lists all available extensions for thiss type. The documentation text equals the javadoc text of the respective method.
/**
* Retrieves the rendering element from the library that has been identified with
* the id
string.
*/
def KRenderingRef getFromLibrary(KRenderingLibrary library, String id) {
[...]
}
Example
It is possible to attach small examples to an extension's documentation that illustrate how
the extension is supposed to be used. For this, add a @example
tag to the
javadoc, followed by the preformatted example. You can add multiple example tags.
<pre>
so that automatic
code formatting does not break its indentation.
/** * Convenient creation of color objects. Allows several names (red, blue, black, etc) * and hex strings (#00ff00). * * @example * rectangle.background = "black".color * rectangle.foreground = "#00ff00".color */ def KColor getColor(String name) { [...] }
Category
By default the extensions are grouped by the type of the class they are applied to. However,
sometimes it is useful to group them by their purpose, for instance styling or
composing extensions. For this add a @extensionCategory
tag to the
javadoc followed by a category identifier. A method can be categorized under multiple
categories, just add multiple tags.
/* * .. a styling method .. * @extensionCategory style */ def KRendering getHairCut(KRendering ren) { [...] } /* * .. a composing method .. * @extensionCategory composing */ def KContainerRendering getNewHouse(KContainerRendering ren) { [...] }