Element Documentation

OpenOffice.org Developer's Guide

IDL Documentation Guidelines

< Previous Section

Next Section >

• File structure
• Element Documentation
• Special Markups
• Special Documentation Tags
• Useful XHTML Tags

< Previous Page

Next Page >

General Element Documentation

Each element consists of three parts:

1. a summary paragraph with XHTML/XML markups
2. the main description with XHTML/XML markups
3. 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.

In contrast to JavaDoc, the first sentence is not used for the summary, but the first paragraph.

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 OpenOffice.org 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.

Do not put normal text behind an @-tag on the same line: /** ... @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.
 
    <nowiki><p><em>Logical</em></nowiki> "Object" in this case means that the interfaces
    actually can be supported by internal (i.e. aggregated) physical
    objects. <nowiki></p></nowiki>
 
    @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.
 
    <nowiki><p>The broadcaster fires the disposing method of this listener if 
    the <method>XComponent::dispose()</method> method is called. </p></nowiki>
 
    @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 );

Content on this page is licensed under the Public Documentation License (PDL).