附录 B: IDL 文档规则
OpenOffice.org API 参考手册是使用 autodoc 工具通过 IDL 文件（其中指定 OpenOffice.org API 中使用的所有类型）自动生成的。这些文件是 SDK 的一部分。此附录讨论如何使用 IDL 文件中的文档注释为 OpenOffice.org API 创建正确的联机文档。
过程
autodoc 工具对这些文件的 UNOIDL 元素和 JavaDoc 之类的特殊文档注释（而不是 C++/Java 样式
注释）进行分析。对于文档中使用的每个元素，其前面都可以使用注释。对于多行文档，注释放在 /** .... */ 中；对于单行文档，注释放在 /// 后。
 |
请勿输入多行文档注释！对于每个元素只会分析最后一行注释，并且在输出中也只显示最后一行注释。
/// This documentation will be lost. /// And this documentation will be lost too. /// Only this line will appear in the output! |
文档中可以使用大部分 XHTML 标记，也就是那些位于 <body>...</body> 标记之间的标记。此外，还支持其他 XML 标记，并可以使用 JavaDoc 样式的 @ 标记。后面将介绍这些内容。
这是一种好方法，因此建议您创建新编写的 IDL 文档的本地化版本，并使用 HTML 客户端浏览文件以检查是否能够正确显示所有版式。
文件装配
每个单独的 IDL 文件仅包含一种类型，即单个接口、服务、结构、枚举、常数组或异常。即使UNOIDL 支持这些嵌套类型，OpenOffice.org 的本地化 API 也不允许使用嵌套类型。
可读和可编辑的结构
IDL 文件的结构必须易于阅读和重新进行编辑。在 autodoc 的输出中将自动生成缩进和换行，但是必需要调整文档注释的简单 ASCII 版式以提高 IDL 文件的可读性。由于包含 HTML 解释，除了 <pre>...</pre> 以及类似区域中的换行以外，输出中将不会出现换行。
除了本文档中提到的指令以外，IDL 文件不应当包含任何 #ifdef 或 #if 指令，因为 OpenOffice.org 社区以及其他社区可以读取这些指令。请勿引入包含强制任务或版本具有依赖性的元素，而是使用 CVS 分支。
避免在文档块前使用星号。当需要重新进行格式化时，必须删除位置不正确的星号，这样就会耗费很多时间。
|
请勿使用前置星号，如下面所示：
/* does something special. * * This is just an example for what you must NOT do: Using leading asterisks. */ |
内容
IDL 文件不应当包含实现所特有的信息。通常将 IDL 文件视为 SDK 交付文件的一部分，这样客户才能看到这些文件。
| Content on this page is licensed under the Public Documentation License (PDL). |
