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 legal reasons, the header has to be exactly as shown in the following snippet. Exceptions of this rule are the dynamic parts within "$...$" and the list of contributors at the end.
/************************************************************************* * * OpenOffice.org - a multi-platform office productivity suite * * $RCSfile: MyNewIDLType.idl,v $ * * $Revision: 1.0 $ * * last change: $Author: jsc $ $Date: 2005/09/07 20:25:41 $ * * The Contents of this file are made available subject to * the terms of GNU Lesser General Public License Version 2.1. * * * GNU Lesser General Public License Version 2.1 * ============================================= * Copyright 2007 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 * ************************************************************************/
The filename in "$RCSfile: MyNewIDLType.idl,v $" is replaced automatically by the version control system, as well as "$Revision: 1.1 $", "$Author: jsc $" and "$Date: 2007/07/05 10:30:56 $". Contributors add their names to the list at the end.
The copyright date has to be adapted to the actual last year of work on the file.
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.
| Content on this page is licensed under the Public Documentation License (PDL). |
