admin 管理员组文章数量: 1086019
2024年4月20日发(作者：docker部署jenkins)
使用 DITADoclet 和 DITA API 规范生成
DITA Java API 参考文档
目标
在本文中，学习如何使用 DITADoclet、DITA Java API 规范和 Eclipse IDE 创建多种格式的 Java API 参
考文档。DITADoclet 生成 DITA Java API 文件，自动创建 Java API 参考文档的 DITAMAP 和
MAPLIST 文件（DITA Java API 规范），从 Java 源代码中直接提取开发人员注释，并把这些信息迁移
到生成的 DITA API 文件中。
常用缩写词
API：应用程序编程接口
CHM：编译的 Windows® HTML 帮助
CSS：层叠样式表
DITA：Darwin Information Typing Architecture
DTD：文档类型定义
HTML：超文本标记语言
IDE：集成开发环境
J2EE：Java 2 平台，企业版
JDK：Java 开发工具箱
JSP：Java Server Pages
URI：统一资源标识符
XHTML：可扩展超文本标记语言
XML：可扩展标记语言
XSLT：可扩展样式表语言转换
通常情况下，使用 Sun Microsystems 提供的 Javadoc 工具从 Java 源代码生成 Java API 参考文档。
Javadoc 能够生成 Java API 参考文档的基本结构，但是文档常常不完整并对开发人员注释有限制。在开
发团队发生变动时，往往倾向于把 API 编写者和编辑完全排斥于 Java API 参考文档过程之外。开发人员
只有时间管理 Java 源代码和不完整的注释。显然，这种情况会给 API 文档编写者和致力于生成高质量
API 文档的其他人造成严重的困难。
API 编写者可以使用 DITADoclet 和 DITA Java API 解决方案提供的工具生成具有完整文档的 Java
API。具有完整文档的 API 可以用于几个用途，但是最重要的用途是让 API 用户能够全面了解、搜索和
浏览可用的 API 功能。为了完整地使用 API 的功能，软件用户需要具有完整准确的文档的 API。
为了解释 DITADoclet 的工作方式，本文还要介绍 Javadoc 标准 doclet 解决方案使用的一些重要概念。
为了让 DITADoclet 自动提取过程能够有效地发挥作用，必须根据 Javadoc 规则在 Java 源代码中添加
注释。否则，在用 DITADoclet 提取注释时，就可能无法准确地处理注释，产生的 API 可能是不完整的。
本文讨论以下主题：
先决条件
什么是 DITA Java API 规范？
DITADoclet 安装
使用 Eclipse Javadoc Generation 向导（标准 doclet）创建 Javadoc 文档
使用以下方式创建 Java API 参考文档：
o
Eclipse Javadoc Generation 向导 (DITADoclet)
o
命令提示
DITADoclet 的优点和缺点
DITADoclet 的下载链接见 参考资料。
可以通过 网站进一步了解 DITA 以及如何创建或编辑 DITA 文件，寻找更多支持 DITA
的 XML 编辑器。强烈建议使用 XML 编辑器以避免在标记中出现错误。有许多 XML 编辑器：Arbortext
Editor™、
等等。我建议使用 Arbortext Editor 作为内容发布系统。
目标读者
本文是为 API 编写者撰写的。假设读者熟悉 Java 软件、Java API 参考文档结构和 Javadoc 生成，而
且作为 API 编写者希望进一步了解如何提供更好的 Java API 参考文档。
API 编写者应该理解开发人员编写的代码，然后把相关信息提取到 API 文档中。要想使用 DITADoclet 成
功地生成 DITA Java API 文档，就必须熟悉 Java 源代码
先决条件
本文解释从 Java 源代码直接生成 Java API 参考 DITA 文件所需的先决条件，以及如何使用 Eclipse 转
换文件。在使用 DITADoclet 和 DITA Java API 规范之前，需要熟悉以下概念：
Java API 参考文档过程和 Javadoc 生成
Eclipse
o
Java IDE 和编辑器的透视图和视图
o
Eclipse 基本概念，比如体系结构、插件和在工作台中插入插件
o
插件的基本元素，比如项目、Eclipse 视图和编辑器
o
如何使用 Eclipse Java IDE 创建、安装和运行简单的插件
Eclipse 是基本 IDE，但是有许多与 Java 相关的 Eclipse 插件，还有一些在 Eclipse 上构建的
商业 IDE：
o
Rational® Software Architect 是一个全面的集成开发环境，支持以图形化方式设计、构
造、测试、分析和部署应用程序
o
Rational Application Developer for WebSphere Software 用图形化开发特性扩展
Eclipse
o
IBM® WebSphere® Studio 是 IBM 提供的一种强大的流行的 J2EE IDE
o
IBM WebSphere Studio Site Developer for Java 是一种用于 Windows 和 Linux 平台
的 Java IDE
o
Sun Java Studio Creator
o
JBuilder
这些产品的下载链接见 参考资料。我建议使用 Eclipse 构建工具或直接从命令提示行运行 DITADoclet。
什么是 DITA Java API 规范？
如果您熟悉 DITA，那么可以跳过本节，跳到下面的 DITADoclet 安装。
DITA 致力于生成一致、完整且正确的技术文档。DITA API 规范是一个包含 DITA 主题类型的包，用于
生成 Java API 文档文件。DITADoclet 从 Java 源代码直接生成 DITA 文件。可以从命令提示或通过使
用 Eclipse 运行它。
Darwin Information Typing Architecture (DITA)
版权声明：本文标题：使用DITADoclet和DITAAPI规范生成DITAJavaAPI参考文档 内容由网友自发贡献，该文观点仅代表作者本人， 转载请联系作者并注明出处：http://www.roclinux.cn/p/1713610828a643243.html， 本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌抄袭侵权/违法违规的内容，一经查实，本站将立刻删除。
发表评论