Special Documentation Tags
This group of special tags are analogous to JavaDoc. Only what has previously been mentioned in this guideline can appear in the line behind these tags. The pertaining text is put into the line following. Each text belonging to a tag ends with the beginning of the next special tag ("@") or with the end of the documentation comment.
@author Name of the Author
This tag is only used if an element is adapted from an externally defined element, that is, a Java class or interface. In this case, the original author and the in-house author at Sun Microsystems is mentioned.
Example:
@author John Doe
@since Product Version
For Apache OpenOffice APIs, all new IDL elements, such as types, properties, and enum values, must use the @since tag to identify in which version the element was introduced.
The document generator tool autodoc translates Product Version into a more human-readable form. OpenOffice.org derivatives can translate it to their own product name and version.
The version number should follow a simple rule: @since OOo <major>.<minor>.[<micro>], where <micro> should be used only if <micro> > 0
Example:
@since OOo 2.1 @since OOo 3.0.1 @since OOo 3.3
@see qualifiedIdentifier
This tag is used for extra cross references to other UNOIDL-specified elements. Some are automatically generated, such as all methods using this element as a parameter or return value, and services implementing an interface or include another service. If there is no other method that should be mentioned or an interface with a similar functionality, it should be referenced by this @see statement.
An @see-line can be followed by further documentation.
Example:
@see com::sun::star::uno::XInterface::queryInterface For this interface you have always access to ...
 |
Do not use markups on the identifier on the same line behind the @see-tag!
/** ... @see <type>these markups are wrong</type */ |
@param ParameterName
This tag describes the formal parameters of a method. It is followed by the exact name of the parameter in the method specification. The parameter by itself may be the implicit subject of the following sentence, if it begins with a lowercase letter.
Examples:
@param xListener contains the listener interface to be added. @param aEvent Any combination of ... can be used in this parameter.
@return/@returns
This tag starts the description of the return value of a method. The description is in the line following. If it begins with a lowercase letter, the method is the implied subject and "returns" is the implied verb. See the following example:
@returns an interface of an object which supports the <type>Foo</type> service.
@throws qualifiedException
This tag starts the description of an exception thrown by a method in a particular case. The exception type is stated behind in the same line and must be fully qualified, if it is not in the same module. The description is in the line following. If it begins with a lowercase letter, the method is the implied subject and "throws" is the implied verb.
Example:
@throws com::sun::star::uno::lang::InvalidArgumentException if the specified number is not a specified ID.
@version VersionNumber
This was originally used to set a version number for the element. This tag is deprecated and should not be used.
| Content on this page is licensed under the Public Documentation License (PDL). |
