Version 1.0.1 December/15/2000
by Michael Hönnig (Michael.Hoennig@Germany.Sun.COM)
<atom> and dim=[]... added to Markups and Tags / Special Markups
The reference manual of the StarOffice API is automatically generated by tools from the IDL-files. The documentation uses the IDL elements and special JavaDoc-like documentation comments of these files, but not normal C++/Java-Style comments. Each element which can be documented has a preceding comment put in "/** .... */" for multiple line documentation comments or put behind "/// ..." for single line documentation comments.
DON'T 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!
First the IDL files get compiled using an uniodl compiler. One of the outputs is XML. The documentation by itself contains embedded XHTML and some special XML tags. The XHTML must be well formed (in pairs with same upper/lower case). This XML is processed by an XSL processor using an XSL stylesheet giving an XSL output file or HTML.
Intermediately there might be a different process, but input (IDL) and output (HTML) remain the same and follow the same rules as well.
Each IDL file must only contain a single type (i.e. a single interface, service, struct, enum, constants group or exception). Nested types are not allowed for StarOffice's native API.
The IDL files have to be structured for easy reading and reediting. Although indentation or line-breaks are generated automatically by the layout tools mentioned above, the simple ASCII layout of the documentation comments has to be structured too for readability. Due to HTML interpretation, such line-breaks of couse do not appear in the output except in <pre>...</pre> and similar areas.
Because IDL files are to be read by customers and the OpenOffice community, they should not contain any other #ifdef or #if directives other than from mentioned in this document. Especially no task force or version dependent stuff. Temporary exceptions are allowed.
AVOID using #ifdef/#if for multiple versions of the file! Better use branches within the version control system.
#if VERSION>350 .... #endif #ifdef INTERNAL .... #endif
Leading asterixes within documentation blocks should be avoided. When reformatting is necessary, it makes a lot work to remove the misplaced asterixes.
DON'T use leading asterixes as show here:
/* does somethings special. * * This is just an example for what you must NOT do: Using leading asterixes. */
IDL files should not contain any implementation specific information. IDL files are part of the ODK delivery, so they are visible by customers.
In this chapter you'll find information about the parts of each IDL file (header, body and footer), the character set to be used and the general layout to be applied.
Lines in the IDL files must not be longer than 78 characters, documentation comment lines must not be longer than 75 characters. Preferable is to use lines shorter than 70 characters. The reason for this is to make it easily readable in any ASCII editor and allows slightly changes (i.e. due to English proof editing) without the need of reformatting.
Only 7-bit ASCII characters can be used in the IDL, 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 such encodings.
In general grammatically complete sentences are to build. One exception is the first sentence of an elements documentation; if it begins with a lower case letter, the described element is the implied subject.
The indentation of sub-elements and for other purposes is to be done by tabs. A tab width of 4 characters is to be used.
Each major element has to be delimited by a 75 to 78 character long line matched by the regular expression "^/\*=*$" from the other major elements. The best way to place it is immediately in the line above the belonging documentation comment. Major elements are typedef, exception, struct, constants, enum, interface and service.
Each major element can be delimited by a 75 to 78 character long line matched by the regular expression "^\t*/\*-*$" from the other minor elements. The best way to place it is immediately in the line above the belonging documentation comment. Minor elements are structure and exception fields, methods and properties.
Interfaces and services supported by services, as single constants are grouped in one of such delimited group.
For legal reasons, the header has to be exactly as follows. Excpetions of cause are the dynamic parts within "$...$" and the list of contributors at the end.
/************************************************************************* * * $RCSfile: documentation_guide.html,v $ * * $Revision: 1.2 $ * * last change: $Author: mi $ $Date: 2000/12/15 14:00:30 $ * * The Contents of this file are made available subject to the terms of * either of the following licenses * * - GNU Lesser General Public License Version 2.1 * - Sun Industry Standards Source License Version 1.1 * * Sun Microsystems Inc., October, 2000 * * * GNU Lesser General Public License Version 2.1 * ============================================= * Copyright 2000 by Sun Microsystems, Inc. * 901 San Antonio Road, Palo Alto, CA 94303, USA * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License version 2.1, as published by the Free Software Foundation. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, * MA 02111-1307 USA * * * Sun Industry Standards Source License Version 1.1 * ================================================= * The contents of this file are subject to the Sun Industry Standards * Source License Version 1.1 (the "License"); You may not use this file * except in compliance with the License. You may obtain a copy of the * License at http://www.openoffice.org/license.html. * * Software provided under this License is provided on an "AS IS" basis, * WITHOUT WARRUNTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, * WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS, * MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING. * See the License for the specific provisions governing your rights and * obligations concerning the Software. * * The Initial Developer of the Original Code is: Sun Microsystems, Inc.. * * Copyright: 2000 by Sun Microsystems, Inc. * * All Rights Reserved. * * Contributor(s): _______________________________________ * * ************************************************************************/
The filename in "$RCSfile: documentation_guide.html,v $" will get replaced automatically by the version control system, as well as "$Revision: 1.2 $", "$Author: mi $" and "$Date: 2000/12/15 14:00:30 $". Contributors should add their names to the list at the end.
The copyright date has to be adapted to the actual last month of work on that file.
The #ifdef/#define consists 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 "_" again as shown above and trailing two underscores "__" again.
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.
Each element consists of three parts:
a summary paragraph with XHTML/XML markups
the main description with XHTML/XML markups
some extra parts formed by @-tags
The first part ending with a a XHTML paragraph tag (ie. <p>, <dl>, <ul>, <ol> etc.) or any "@..." tag is used as the summary in indexes.
The first sentence may begin with a lower case character if the name of the described element is the implied noun. But in this case the sentence must make sense reading it with that name in mind. Sometimes that means, an auxiliary verb (in the most cases "is") has to be inserted.
Between the summary paragraph and the "@..." tag part 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>", "<ol>" etc.,. which are starting a new paragraph too.
At the end of each element's documentation some of the @-tags can be put. Which do make sense depends on the kind of element which is described. Each of the @-tag parts 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. But if there are external authors for major elements, they and the adapting author should be mentioned.
The @version tag known from JavaDoc is not valid here, because due to compatibility there cannot be more than one version of IDL elements.
On the same line behind the @-tag only a single structural element is allowed. For @param this is the parameter name, without the type and any attributes, for @throws this is the qualified exception, for @see this is the qualified type, for @example it's the programming language. @returns must not have anything else on the same line.
DON'T 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.
*/
Each major element gets a header like shown here in an example for an interface:
//=========================================================================== /** controls lifetime of the object. <p><em>Logical</em> "Object" in this case means that the interfaces actually can be supported by internal (i.e. aggregated) physical objects. </p> @see com::sun::star::uno::XInterface for further information. */ [ uik(g227g391-33d6-11g1-gabe00a0-249d5590), ident("XComponent", 1.0) ] interface XComponent: XInterface {
Comment: The UIK shown above is neither the correct one nor syntactically correct (contains "g"). That is to avoid getting it copied and so raising ID-conflicts.
Each minor element gets a header like shown here in an example for a method:
/------------------------------------------------------------------------ /** adds an event listener to the object. <p>The broadcaster fires the disposing method of this listener if the <method>XComponent::dispose()</method> method is called. </p> @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 );
These markup tags will be evaluated by the XSL processor which is used to generate a layouted version of the documentation, i.e. into HTML. These tags have to be well formed (in pairs with exactly the same upper/lower case) as well.
To accentuate identifiers in the generated documentation and to generate hyperlinks automatically as building the cross-reference table and check consistency, all identifiers have to get marked up. Additionally that is important for proofreading, because especially a single-word method name could not be distinguished by a verb. And identifiers have to be excluded from reediting by the proof editor.
The following markups are used:
This markup is used for identifiers of atomar types, like long, short, string etc.. If a sequence/array of the type is referred, add the attribute dim with the number of bracket-pairs which represent the number of dimensions.
Example:
<type>long</type>
This markup is used for identifiers of interfaces, services, typedefs, structs, exceptions, enums and constants-groups. If a sequence/array of the type is referred, add the attribute dim with the number of bracket-pairs which represent the number of dimensions.
Example:
<type scope="com::sun::star::uno">XInterface</type>
<type dim="[][]">PropertyValue</type>
This markup is used for fields of structs and exceptions, properties in service specifications and for methods of interfaces.
Example:
<member scope="com::sun::star::uno">XInterface::queryInterface()</member>
This markup is used for symbolic constant identifiers of constant groups and enums.
Example:
<const scope="...">ParagraphAdjust::LEFT</const>
This markup represents the atomic constant for a boolean TRUE value.
Example:
@returns <TRUE/> if the number is valid, otherwise <FALSE/>.
This markup represents the atomic constant for a boolean FALSE value.
This markup represents the atomic constant for a NULL value.
This markup represents the atomic type void.
This markup is used for inline code.
Example:
Use <code>queryInterface( NULL )</code> for ...
This markup is used for multiple line code examples.
Example:
@example StarBASIC <listing> aCmp = StarDesktop.loadComponentFromURL( ... ) if ( isnull(aCmp) ) .... endif </listing>
These group of special tags are mostly analog to JavaDoc. In the same line behind the tag is only allowed what is mentioned in this guideline. The belonging text is to put in the following line. Each text what belongs to a tag ends with the beginning of the next special tag ("@") or with the end of the documentation comment.
This tag should only be used if an element is adapted from an externally defined element (i.e. a Java class or interface). In this case the original author and the inhouse author is to mention.
Example:
@author John Doe
This tag is used for extra cross references to other IDL-specified elements. Some are automatically generated, like all methods which used this element as a parameter or return value, services which implement an interface or include another service etc. But if there i.e. Another method what should be mentioned or an interface with a similar functionality, it should be referred by this see statement.
Such a @see-line can be followed by further documentation; see example.
Example:
@see com::sun::star::uno::XInterface::queryInterface For this interface you have always acces to ...
DON'T use markups on the identifier on the same line behind the @see-tag!
/** ... @see <type>these markups are wrong</type */
This tag is used to describe 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 lower case letter.
Examples:
@param xListener contains the listener interface to be added. @param aEvent Any combination of ... can be used in this parameter.
This tag starts the description of the return value of a method. The description follows in the next line. If it begins with a lower case letter, the method is the implied subject and "returns" is the implied verb; see example.
Examle:
@returns an interface of an object which supports the <type>Foo</type> service.
This tag starts the description of an exception which is thrown by a method in a certain case. The exception type is stated behind in the same line; and it must be fully qualified if it is not in the same module. The description follows in the next line. If it begins with a lower case letter, the method is the implied subject and "throws" is the implied verb; see example.
Example:
@throws com::sun::star::uno::lang::InvalidArgumentException if the specified number is not a specified ID.
Was originally used to set a version number for the element. This tag should not be used anymore.
For writing the documentation in IDLs only a few HTML tags are really needed. The most important I have listed here. For all HTML tags the end-tag is optional if it is put in brackets "[...]" here:
This tag marks up a normal paragraph. Please keep in mind that line breaks and empty lines in the IDL do not cause a line break or a paragraph break in the layouted version. Explicit paragraph break markups are necessary.
DON'T use <br/> or CR/lF for marking up paragraphs. CR/LF will simply be ignored, except within <pre>...</pre> and <listing>...</listing> areas. <br/> is only for rare cases of explicit linebreaks.
/** does this and that. This sentence should start with a "<p>". If not, it still belongs to the previous paragraph! This still belongs to the first paragraph. <br> As this sentence is as well! */
This tag marks up a line break within the same paragraph. Please keep in mind that line breaks and empty lines in the IDL do not cause a line break or a paragraph break in the layouted version. Explicit paragraph break markups are necessary.
These tags mark up the beginning and end of an unordered list, as the list items by itself.
Example:
<ul> <li>the first item </li> <li>the second item </li> <li>the third item </li> </ul> results in:
the first item
the second item
the third item
These tags mark up the beginning and end of an ordered list, as the list items by itself.
<ol> <li>the first item </li> <li>the second item </li> <li>the third item </li> </ol> results in:
the first item
the second item
the third item
These tags mark up the beginning and end of a definition list, the definition tags and the definition data.
<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 something like:
the first item
asfd asdf asdf asdf asdf
the second item
asfd asdf asdf asdf asdf
the third item
asfd asdf asdf asdf asdf
Defines a table with rows (tr) and columns (td).
These tags are used to put a piece of text strongly emphasized. In the most cases it is bold, but what it actually is, is defined by the HTML-client.
These tags are used to put a piece of test slightly emphasized. In the most cases it is italic, but what it actually is, is defined by the HTML-client.
These tags are used to specify a link to external documentation. The first "..." specifies the URL.
(C) 1999, Star Office Entwicklungs GmbH, Hamburg