LibreOffice Developer's Guide: Appendix B - IDL Documentation Guidelines
The reference manual of the LibreOffice API is automatically generated by the tool autodoc from the idl files that specify all types used in the LibreOffice API. These files are part of the SDK. This appendix discusses how documentation comments in the idl files are used to create correct online documentation for the LibreOffice API.
Process
The autodoc tool evaluates the UNOIDL elements and special JavaDoc-like documentation comments of these files, but not the C++/Java-Style comments. For each element that is documented, the preceding comment is used. Put the comment within /** .... */ for multiple-line documentation, or put behind /// for single-line documentation.
 |
Warning: /// This documentation will be lost. /// And this documentation will be lost too. /// Only this line will appear in the output!
|
Most XHTML tags can be used within the documentation, that is, only tags that occur between the <body>...</body> tags. Additionally, other XML tags are supported and JavaDoc style @-tags can be used. These are introduced later.
It is good practice and thus recommended to build a local version of newly written IDL documentation and browse the files with an HTML client to check if all your layouts appear correctly.
File Assembly
Each individual idl file only contains a single type, that is, a single interface, service, struct, enum, constants group or exception. Nested types are not allowed for LibreOffices local API., even though they are supported by UNOIDL.
Readable & Editable Structure
The idl files have to be structured for easy reading and re-editing. Indentation or line-breaks are generated automatically in the output of autodoc, but the simple ASCII layout of the documentation comments has to be structured for readability of the idl files. Due to HTML interpretation, the line-breaks do not appear in the output, except in
...
and similar areas.
The idl files should not contain any #ifdef or #if directives than those mentioned in this document because they are read by the OpenOffice.org community and others. Do not introduce task force or version dependent elements, use CVS branches instead.
Avoid leading asterisks within documentation blocks. Misplaced asterisks must be removed when reformatting is necessary, thus time consuming.
|
Warning: /* does something special. * * This is just an example for what you must NOT do: Using leading asterisks. */
|
Contents
The idl files should not contain implementation specific information. Always consider idl files as part of the SDK delivery, so that they are visible to customers.
File structure
This chapter provides information about the parts of each idl file, such as the header, body and footer, the character set to be used and the general layout to be applied.
General
Length of Lines
Lines in the idl files should not be longer than 78 characters, and documentation comment lines should not be longer than 75 characters. The preferable length of lines is upto 70 characters. This makes it readable in any ASCII editor and allows slight changes, that is, due to English proofreading without the need of reformatting.
Character Set and Special Characters
Only 7-bit ASCII characters are used in UNOIDL, even in the documentation comments. If other characters are necessary, the XHTML representation is to be used. See http://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent for a list of the encodings.
Completeness of Sentences
In general, build grammatically complete sentences. One exception is the first sentence of an elements documentation, it may begin with a lowercase letter, in which case the described element itself is the implied subject.
Indentation
The indentation of sub-elements and for others is four spaces for each level of indentation.
Delimiters
Each major element has to be delimited by a 75 to 78-character long line from the other major elements. This line consists of “//” followed by equal signs to match the regular expression "^/\*=*$". Place it immediately in the line above the documentation comment that it belongs to.
Major elements are typedef, exception, struct, constants, enum, interface and service.
The sub elements can be delimited by a 75 to 78-character long line matched by the regular expression "^ \( \)*/\*-*$" from the other minor elements and the major element. This is a line consisting of a multiple of four spaces, followed by “//” and dashes. Place it immediately in the line above the documentation comment that it belongs to. Minor elements are structure and exception fields, methods and properties. Interfaces and services supported by services as single constants are to be grouped by delimiters.
Examples for major and minor elements are given below.
File-Header
For the license, use guidelines from core/TEMPLATE.SOURCECODE.HEADER
The #ifdef and #define identifiers consist of two underscores "__", the module specification, each nested module separated by a single underscore "_" and the name of the file separated with a single underscore "_" as shown above and trailing two underscores "__".
The files do not have a footer with VCS fields. The history can only be viewed from CVS directly. This is to avoid endless expanding log lists.
Element Documentation
General Element Documentation
Each element consists of three parts:
- a summary paragraph with XHTML/XML markups
- the main description with XHTML/XML markups
- extra parts formed by @-tags
Summary Paragraph
The first part ending with an XHTML paragraph tag, that is, <p>, <dl>, <ul>, <ol> etc.) or "@..." tag, is used as the summary in indexes.
|
Warning:
|
The first sentence begins with a lowercase letter if the name of the described element is the implied noun. In this case, the sentence must be logical when reading it with that name. Sometimes an auxiliary verb. in the most cases "is", has to be inserted.
Main Description
Between the summary paragraph and the "@..." tag there should be a clear and complete description about the declared element. This part must be delimited from the summary paragraph with an XHTML paragraph tag, including "<dl>" and "<ol>", that are starting a new paragraph.
@-Tagged Part
Put the @ tags at the end of each element's documentation. The tags are dependent on the kind of element described. Each of the @-tag ends when the elements documentation ends or the next @-tag begins.
The @author tag is superfluous, because the author is logged by the version control system. They are only used for LibreOffice contributions if declarations are taken from other projects, such as Java.
The @version tag, known from JavaDoc, is not valid, because there cannot be more than one version of any UNOIDL element, due to compatibility.
On the same line behind the @-tag, only a single structural element is allowed. The parameter name is @param without the type and any attributes, the qualified exception is @throws , the qualified type is @see, and the programming language is @example. The @returns is by itself on the same line.
|
Warning: /** ... @param nPos put nothing else but the argument name here! it is correct to put your documentation for the parameter here. @throws com::sun::star::beans::UnknownPropertyException nothing else here! when <var>aName</var> is not a known property. */
|
Example for a Major Element Documentation
Each major element gets a header similar to the example shown below for an interface:
//===========================================================================
/** controls lifetime of the object. Always needs a specified object owner.
Logical "Object" in this case means that the interfaces
actually can be supported by internal (i.e. aggregated) physical
objects.
@see com::sun::star::uno::XInterface
for further information.
@since OOo 2.1.0
*/
interface XComponent: XInterface
{Example for a Minor Element Documentation
Each minor element gets a header similar to the example shown below for a method:
//------------------------------------------------------------------------
/** adds an event listener to the object.
The broadcaster fires the disposing method of this listener if
the <method>XComponent::dispose()</method> method is called.
@param xListener
refers the the listener interface to be added.
@returns
<TRUE/> if the element is added, <FALSE/> otherwise.
@see removeEventListener
*/
boolean addEventListener( [in]XEventListener xListener );Special Markups
These markup tags are evaluated by the XSL processor that generates a layout version of the documentation, that is, into HTML or XHTML. These tags have to be well formed and in pairs with exactly the same upper and lowercase, as well.
To accentuate identifiers in the generated documentation and generate hyperlinks automatically when building the cross-reference table and checking consistency, all identifiers have to be marked up. Additionally, it is important for proofreading, because a single-word method name cannot be distinguished by a verb. Identifiers have to be excluded from re-editing by the proofreading editor.
The following markups are used:
<atom>
This markup is used for identifiers of atomar types, such as long, short, and string. If a sequence or array of the type is referred to, add the attribute dim with the number of bracket-pairs representing the number of dimensions.
Example:
<atom>long</atom>
For an example of sequences, see <type>.
<type>
This markup is used for identifiers of interfaces, services, typedefs, structs, exceptions, enums and constants-groups. If a sequence or array of the type is referred to, add the attribute dim with the number of bracket-pairs representing the number of dimensions.
Example:
<type scope="com::sun::star::uno">XInterface</type>
<type dim="[][]">PropertyValue</type><member>
This markup substitutes the deprecated method, field and property markups, and is used for fields of structs and exceptions, properties in service specifications and methods of interfaces.
Example:
<member scope="com::sun::star::uno">XInterface::queryInterface()</member><const>
This markup is used for symbolic constant identifiers of constant groups and enums.
Example:
<const scope="...">ParagraphAdjust::LEFT</const>
<TRUE/>, <FALSE/>
These markups represent the atomic constant for the boolean values TRUE and FALSE.
Example:
@returns <TRUE/> if the number is valid, otherwise <FALSE/>.
<NULL/>
This markup represents the atomic constant for a NULL value.
<void/>
This markup represents the atomic type void. This is identical to <atom>void</atom>.
<code>
This markup is used for inline code.
Example:
Use queryInterface( NULL ) for:
<listing> This markup is used for multiple line code examples. Example: @example StarBASIC <listing> aCmp = StarDesktop.loadComponentFromURL( ... ) if ( isnull(aCmp) ) .... endif </listing>
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 LibreOffice 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 ...
|
Warning: /** ... @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.
Useful XHTML Tags
Only a few XHTML tags are required for writing the documentation in idl files. The most important ones are listed in this section.
Paragraph: <p> ... </p>
This tag marks a normal paragraph. Consider that line breaks and empty lines in the idl file do not cause a line break or a paragraph break in the layout version. Explicit paragraph break markups, are necessary.
|
Warning: Consider using < for < and > for >, as shown in the example above.
|
Line Break: <br/>
This tag marks up a line break within the same paragraph. Consider line breaks and empty lines in the idl file do not cause a line break or a paragraph break when presented by the HTML browser. Explicit paragraph break markups are necessary.
Unordered List: <ul><li> ... </li>... </ul>
These tags mark the beginning and end of an unordered list, as list items.
Example:
<ul>
<li>the first item </li>
<li>the second item </li>
<li>the third item </li>
</ul>results in a list similar to:
- the first item
- the second item
- the third item
Ordered List: <ol><li> ... </li>... </ol>
These tags mark the beginning and end of an ordered list, as list items.
Example:
<ol>
<li>the first item </li>
<li>the second item </li>
<li>the third item </li>
</ol>results in a list similar to:
1.the first item
2.the second item
3.the third item
Definition List: <dl><dt> ... </dt><dd> ... </dd>... </dl>
These tags mark the beginning and end of a definition list, the definition tags and the definition data.
Example:
<dl>
<dt>the first item</dt>
<dd>asfd asdf asdf asdf asdf</dd>
<dt>the second item</dt>
<dd>asfd asdf asdf asdf asdf</dd>
<dt>the third item</dt>
<dd>asfd asdf asdf asdf asdf</dd>
</dl>results in a list similar to:
the first item
- asfd asdf asdf asdf asdf
the second item
- asfd asdf asdf asdf asdf
the third item
- asfd asdf asdf asdf asdf
Table: <table><tr><td>...</td>...</tr>...</table>
Defines a table with rows (tr) and columns (td).
Strong Emphasis: <strong> ... </strong>
These tags present a piece of text that is emphasized. In most cases this is bold, but the HTML-client defines what it actually is.
Slight Emphasis: <em> ... </em>
These tags present a piece of text emphasized slightly. In most cases this is italic, but the HTML-client defines what it actually is .
Anchor: <a href="..."> ... </a>
These tags specify a link to external documentation. The first "..." specifies the URL.
 |
Content on this page is licensed under the Public Documentation License (PDL).
|