Appendix B: IDL Documentation Guidelines

From Apache OpenOffice Wiki
Jump to: navigation, search



PDF Icon.gif Download as a PDF or ODT


The reference manual of the Apache OpenOffice API is automatically generated by the tool autodoc from the idl files that specify all types used in the Apache OpenOffice 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 Apache OpenOffice 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.

Documentation caution.png Do not put multiple documentation comments! Only the last will be evaluated for each element and appear in the output.
 /// 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 Apache OpenOffices 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 <pre>...</pre> 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.

Documentation caution.png Do not use leading asterisks as shown here:
 /* 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.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages