How to Annotate Extension Classes

Class

To make a class available to this documentation add a @containsExtensions tag to the class' javadoc.

Example
                                /**
                                 * @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.

Example
                                /**
                                 * @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.

It is possible to use arbitrary html within the documentation text.
Example
                                /** 
                                 * 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.

You can surround the example with <pre> so that automatic code formatting does not break its indentation.
Example
                                /**
                                 * 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.

Example
                                /*
                                 * .. a styling method ..
                                 * @extensionCategory style
                                 */
                                def KRendering getHairCut(KRendering ren) {
                                    [...]
                                }
                                 
                                 /*
                                 * .. a composing method ..
                                 * @extensionCategory composing
                                 */
                                def KContainerRendering getNewHouse(KContainerRendering ren) {
                                    [...]
                                }