java8api参考文档_Java API参考文档

java8api参考文档

背景

改善产品文档的适用性是许多项目成功的关键。成功与否直接归因于您努力生成和编写良好的文档。

本资料假定您熟悉Java软件，Java API参考文档结构，Javadoc生成，并且想进一步了解如何提供改进的Java API参考文档。
对于初学者，您应该熟悉以下这些：

Javadoc，由Sun Microsystems创建的开源工具。有关更多信息，请阅读java.sun/j2se/javadoc 。
JavaHelp，一个具有索引和搜索功能的帮助集。有关更多信息，请参见java.sun/products/javahelp 。
JavaHelp中的创作工具。有关更多信息，请参考java.sun/products/javahelp/industry.html上的列表。
标准Java编码约定
Javadoc约定。有关详细信息，请参见java.sun/j2se/javadoc/writingdoccomments 。

构建易于使用且可搜索的Java API参考文档

本文介绍了用于生成易于使用和可搜索的Java应用程序编程接口（API）参考文档的不同方法。所描述的方法是Javadoc标准解决方案和使用我开发的JavaTOC doclet生成的Eclipse插件帮助系统。 JavaTOC doclet为Javadoc API参考文档创建目录（TOC），帮助用户轻松地在API参考文档中搜索特定的类，接口或方法。

Javadoc API参考文档需要可浏览和可搜索。标准Javadoc不能完全提供此功能。完整记录的API可以用于多种目的，但是最重要的原因是允许用户完全理解和搜索对他们可用的API函数。如果没有正确记录或搜索，甚至原始作者也可能不理解源代码。解决方案是养成记录源代码的习惯，并为Java API参考创建可搜索的结构（TOC导航）。 JavaTOC doclet通过为引用创建可搜索的结构来解决此问题。

搜索和浏览假定针对特定查询按相关性对信息进行排序，从而创建任意数量的临时序列。例如，在标准Javadoc中，搜索API信息以获取对特定方法的描述，以返回整个类的描述。

考虑的方法

解决方案是养成记录源代码的习惯。如果没有正确记录，甚至原始作者也可能不理解源代码。

有很多用于生成Java API参考文档的工具。我当前的建议是与Javadoc或DITA API专业化结合使用的JavaTOC doclet。

Javadoc是Sun拥有的工具，可以从Java源代码中提取开发人员注释并将其输出到HTML。 Javadoc工具生成Java API参考文档的基本结构。结果是一组软件包和类的Javadoc HTML API文档。
JavaTOC doclet为Java API参考文档生成TOC导航和搜索功能。 IBM DITA API专业化团队已经开发了一套DITA主题类型，以生成Java API文档文件和用于参考的导航清单，这些参考清单将包含在Eclipse帮助系统中。

以下示例（ 不带toc导航 的API参考示例和带toc导航的API参考示例 ）使用DITA Open Toolkit中的Java源代码。 DITA Open Toolkit版本1.0.2或更高版本提供了一个命令提示符界面，作为不熟悉Ant的用户可以轻松使用该工具箱的替代方法。下载zip文件后，您可以在DITA-OT1.2_src \ DITA-OT1.2-src \ src目录中找到用于本文示例的源代码。

关于Javadoc和JavaTOC doclet

标准Javadoc帮助和定制的Eclipse Javadoc帮助之间的最大区别是提供的TOC导航。标准的Javadoc帮助提供了两个额外的框架，可让您浏览包和类。定制的Eclipse Javadoc帮助包含Eclipse样式的XML导航文件，而不是那些多余HTML框架。 Eclipse样式的XML导航文件创建TOC导航，该目录允许用户搜索特定的包，类或接口。定制的Eclipse Java API参考解决方案提供了将在Eclipse帮助系统中包含的文档的导航清单。

整个Eclipse平台都是围绕插件的思想开发的。如果要将帮助文档贡献给Eclipse平台，则必须开发一个新的帮助插件。该插件由HTML和图像文件，XML中的目录文件以及清单文件组成。 JavaTOC doclet自动生成整个Eclipse插件结构，包括直接从Java源代码提取的XML导航TOC文件。

JavaTOC doclet是一个自定义程序，也可以与Javadoc工具一起使用。 doclet提供了更大的灵活性，使您可以在Javadoc文档文件的顶部生成TOC导航。

JavaTOC doclet与DITAdoclet工具集成在一起，该工具用于IBM DITA API专业化，该工具专门用于生成Java DITA（XML）API文件，用于记录和生成Java API参考。该解决方案还包括Java API参考文档的导航清单，该清单将包含在Eclipse帮助系统中。

使用标准Javadoc工具生成的Eclipse Javadoc API参考结构

要在Eclipse中访问标准Javadoc联机帮助，可以在菜单栏上选择“ 帮助”>“帮助内容 ”。这将在其自己的浏览器中显示联机帮助。
在左窗格中，有一个选项卡式视图，用于目录，搜索和上下文相关的帮助链接。下面的示例（图1）显示了标准的Javadoc API引用结构。它是在Eclipse环境中仅使用标准Javadoc工具生成的。

图1. Javadoc API引用结构

org.eclipse.help.toc的扩展点将其标识为帮助系统的插件。

清单1. plug-in.xml

<?xml version="1.0" encoding="UTF-8"?>
 <?eclipse version="1.0"?>

 <plugin>

  <extension point="org.eclipse.help.toc">
   < toc file="doclet.toc.xml" primary="true"/>
  </extension>

</plugin>

清单2. MANIFEST.MF

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Doc Plug-in
Bundle-SymbolicName: org.dita.dost.doc; singleton:=true 
Bundle-Version: 1.0.0
Bundle-Activator: org.dita.dost.doc.DocPlugin
Bundle-Localization: plugin
Require-Bundle: org.eclipse.ui,
 org.eclipse.core.runtime
Eclipse-AutoStart: true

要么

清单3. plug-in.xml

<?xml version="1.0" encoding="UTF-8"?>
 <?eclipse version="1.0"?>

 <plugin
    name = "%Plugin.name"
    id = "org.dita.dost.user.doc"
    version = "7.0.1.0"
    provider-name = "%Plugin.providerName">

  <extension point="org.eclipse.help.toc">
   < toc file="doclet.toc.xml" primary="true"/>
  </extension>

</plugin>

将插件的名称，ID，版本和提供程序名称更改为适合您的项目的值。

清单4. plugin.properties

# NLS_MESSAGEFORMAT_VAR
# ==============================================================================
# Online Help - Translation Instruction: section to be translated
# =============================================================================
Plugin.name = Building DITA output
Plugin.providerName = IBM

doclet.toc.xml文件被引用为该插件的目录。该文件将在Eclipse帮助窗口的左窗格中提供分层信息的数据。一个简单的文件包含清单2中所示的内容。

清单5. doclet.toc.xml

<?xml version="1.0" encoding="UTF-8"?>
 <?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Building DITA output">
   <topic label="API References" href="index.html"/>
</toc>

其中href =“ index.html”是创建的javadoc api引用的链接。如果希望在右窗格中打开不带HTML框架的文档，则链接将为href =“ overview-summary.html”。

标准Javadoc导航栏组织

标准Javadoc导航栏不允许用户搜索特定的包，类或方法。
SUN Javadoc就是这样组织和描述Javadoc选项卡导航的-图2。

图2. Javadoc选项卡导航

要创建包注释文件，必须将其命名为package.html并将其与.java文件一起放置在源树的package目录中。 Javadoc将在此位置自动查找此文件名。请注意，所有软件包的文件名都相同。

包注释文件的内容是一个大的文档注释，与所有其他注释一样，都是用HTML编写的，但有一个例外：
文档注释不应包含注释分隔符/ **和* /或前导星号。在写评论时，您应该使第一句话成为关于程序包的摘要，并且不要在第一句之间加上标题或任何其他文本。
您可以包含包装标签；与任何文档注释一样，除{@link}外的所有标签都必须出现在说明之后。如果在软件包注释文件中添加@see标记，则该标记必须具有完全限定的名称。

SUN Javadoc将生成源自四种不同类型的“源”文件的输出：
类的Java语言源文件（.java），程序包注释文件，概述注释文件和其他未处理的文件。

总览

概述页面是此API文档的首页，并提供所有软件包的列表以及每个软件包的摘要。此页面还可以包含一组软件包的整体描述。 观察：

不要忘记在名为Overview.html的文件中编写包级Javadoc。该文件应放置在代码文件所在的根目录中。 Javadoc能够提取该文件并使用其内容

。

包

每个软件包都有一个页面，该页面包含其类和接口的列表，以及每个类的摘要。该页面可以包含五个类别： 接口，类，异常，错误和常量。
观察：

不要忘记在名为package.html的文件中编写包级别的Javadoc。该文件应放在该程序包的代码文件所在的目录中。 Javadoc能够提取该文件并使用其内容

。

类/接口

每个类，接口，内部类和内部接口都有自己的单独页面。每个页面都有三个部分，包括类/接口描述，摘要表和详细的成员描述：
每个摘要条目都包含该项目详细说明中的第一句话。
摘要条目是按字母顺序排列的，而详细说明则按照它们在源代码中出现的顺序排列。这保留了程序员建立的逻辑分组。

用

每个文档包，类和接口都有其自己的“使用”页面。该页面描述了哪些包，类，方法，构造函数和字段使用给定类或包的任何部分。

树（类层次结构）

所有包都有一个树（类层次结构）页面，每个包都有一个层次结构。每个层次结构页面都包含一个类列表和一个接口列表。

不推荐使用

“不推荐使用的API”页面列出了不推荐使用的整个API。不推荐使用不推荐使用的API，通常是由于改进，通常会提供替换的API。在以后的实现中，可能会删除不赞成使用的API。

指数

该索引包含所有类，接口，构造函数，方法和字段的字母列表。

这些链接将您带到下一个或上一个类，界面，包或相关页面。

框架/无框架

这些链接显示和隐藏HTML框架。所有页面均可带或不带框架。

使用JavaTOC doclet生成的Eclipse Javadoc API参考结构

使用Eclipse JavaTOC doclet和Javadoc帮助样式的XML等结构化信息方法可以满足可浏览和可搜索的Java API参考文档的需求。

要在Eclipse帮助插件中启用导航，Information Developer必须提供以XML文档形式编写的目录（TOC）。该文档的左侧提供了可折叠索引，右侧提供了HTML文档。可以使用Javadoc或IBM DITA Java API专业化来创建HTML文件。

您可以手动创建目录，也可以使用JavaTOC doclet自动创建目录。 JavaTOC doclet为您生成Java API参考TOC结构，其中列出了软件包以及所包含的类和接口。

要创建API参考HTML文件，您可以运行Javadoc工具或使用IBM DITA API专业化解决方案来创作和生成Java API参考HTML文件-图3。

图3. HTML-Kit编辑器

如果您使用JavaTOC doclet，则API参考文档既可浏览又可搜索。由于使用了结构化信息方法（XML），因此搜索功能成为可能。

使用XML生成API参考文档结构的积极副作用之一是，将自动为搜索内容建立索引。如果您使用标准Javadoc解决方案来生成内容，则默认情况下不会为搜索建立索引。

Eclipse Java API参考结构和TOC生成必需的文件

以下清单提供了用于生成上述Java API参考TOC导航结构的TOC XML文件的示例。可以手动或使用JavaTOC doclet自动生成文件。请参阅下面的下载部分，以下载Eclipse的Java API参考XML TOC示例。

以下清单显示了一个引用一个TOC XML文件的Eclipse Java API参考插件的示例。

清单6. plug-in.xml

<?xml version="1.0" encoding="UTF-8"?>
 <?eclipse version="1.0"?>

 <plugin>

  <extension point="org.eclipse.help.toc">

  <toc file="doclet.toc.xml" primary="true"/>

  </extension>

</plugin>

以下清单显示了Eclipse Java API参考插件的相同示例，该插件基于Java包结构参考了多个TOC XML文件。查看文档时，使用一个TOC或多个TOC XML文件方法没有什么区别。

清单7. plug-in.xml

<?xml version="1.0" encoding="UTF-8"?>
 <?eclipse version="1.0"?>

 <plugin
    name = "%Plugin.name"
    id = "org.dita.dost.user.doc"
    version = "7.0.1.0"
    provider-name = "%Plugin.providerName">

  <extension point="org.eclipse.help.toc">

   <toc file="doclet.toc.xml" primary="true"/>

    <toc file="org.dita.dost.exception.toc.xml"/>
    <toc file="org.dita.dost.index.toc.xml"/>
    <toc file="org.dita.dost.invoker.toc.xml"/>
    <toc file="org.dita.dost.log.toc.xml"/>
    <toc file="org.dita.dost.module.toc.xml"/>
    <toc file="org.dita.dost.pipeline.toc.xml"/>
    <toc file="org.dita.dost.platform.toc.xml"/>
    <toc file="org.dita.dost.reader.toc.xml"/>
    <toc file="org.dita.dost.util.toc.xml"/>
    <toc file="org.dita.dost.writer.toc.xml"/>


  </extension>

</plugin>

您可以使用navref和anchor元素，以及map元素的anchorref属性，以在Eclipse输出中生成集成点，在该输出中，导航文件会在运行时被拉入或附加到自身。请参阅Eclipse参考资料，以获取有关编写Eclipse导航文件的更多信息。

清单8. doclet.toc.xml

<?xml version="1.0" encoding="UTF-8"?>
 <?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Building DITA output">
   <topic label="Overview" href="doc\overview-summary.html">
        <link toc="org.dita.dost.exception.toc.xml"/>
        <link toc="org.dita.dost.index.toc.xml"/>
        <link toc="org.dita.dost.invoker.toc.xml"/>
        <link toc="org.dita.dost.log.toc.xml"/>
        <link toc="org.dita.dost.module.toc.xml"/>
        <link toc="org.dita.dost.pipeline.toc.xml"/>
        <link toc="org.dita.dost.platform.toc.xml"/>
        <link toc="org.dita.dost.reader.toc.xml"/>
        <link toc="org.dita.dost.util.toc.xml"/>
        <link toc="org.dita.dost.writer.toc.xml"/>
 </topic>
</toc>

主要XML目录必须具有标题（在Eclipse中为标签），以便加载该帮助的目录。

文件org.dita.dost.index.toc.xml只是另一个目录，并且应该采用与其他toc.xml文件完全相同的格式。

清单9. org.dita.dost.index.toc.xml

<?xml version="1.0" encoding="UTF-8"?>
 <?NLS TYPE="org.eclipse.help.toc"?>

<toc label="org.dita.dost.index Package" link_to="../doclet.toc.xml#java.packages">
  <topic label="org.dita.dost.index Package" 
  href="doc/org/dita/dost/index/package-overview.html">
           <anchor id="org.dita.dost.index.packages"/>
    <topic label="IndexTerm" href="doc/org/dita/dost/index/IndexTerm.html"/>
    topic label="IndexTermCollection" 
    href="doc/org/dita/dost/index/IndexTermCollection.html"/>
    <topic label="IndexTermTarget" href="doc/org/dita/dost/index/IndexTermTarget.html"/>
    <topic label="TopicrefElement" href="doc/org/dita/dost/index/TopicrefElement.html"/>
  </topic>
</toc>

在将新的API文档编辑或添加到源代码文件后，您应该生成文档以确保结果符合预期。

在Eclipse 3.2中，整个doc插件可以作为单个jar文件提供，其中包括将进入doc.zip文件的所有文件以及常规插件文件：manifest.mf，插件。 xml，plugin-in.properties等。在Eclipse 3.2之前，生成的Javadoc文件将与静态HTML文件和扩展点架构HTML文件一起保存在doc.zip文件中。

未记录的代码难以理解，无法使用，无法管理。 JavaToc doclet是有价值的工具。我确实希望本文能帮助您找到将JavaToc doclet集成到项目中的兴趣。

告示

“简单是效率的灵魂”。 —奥斯汀·弗里曼

“我们今天生活在一个专业化的时代。每个知识领域中可用的信息量如此之大，以至于要理解和使用它，必须成为专家。随着越来越多的物质知识变得可用，需要增长，以使研究更加多样化和专家更多。”

本文档中提供的信息尚未提交任何正式的IBM测试，而是“按原样”分发，没有任何明示或暗示的保证。
使用此信息或本文档中描述的任何这些技术的实现是读者的责任，并且取决于读者评估它们并将其集成到其操作环境中的能力。

结论

未来的文章，即使用JavaTOC doclet生成的Eclipse Java API参考结构，将描述使用JavaTOC doclet和Eclipse Plug-in Help系统自动生成可搜索的Java API参考文档（TOC导航）的过程。在本系列的后续文章中，我们还将更深入地了解API文档的编写和生成技术以及IBM的一些增值增强功能，包括Java DITA API的专业化以及如何使用它。

翻译自: https://www.ibm/developerworks/rational/library/07/0320_alupului/index.html

java8api参考文档

更多推荐

java8api参考文档_Java API参考文档

java8api参考文档_Java API参考文档

背景

构建易于使用且可搜索的Java API参考文档

考虑的方法

关于Javadoc和JavaTOC doclet

使用标准Javadoc工具生成的Eclipse Javadoc API参考结构

图1. Javadoc API引用结构

清单1. plug-in.xml

清单2. MANIFEST.MF

清单3. plug-in.xml

清单4. plugin.properties

清单5. doclet.toc.xml

标准Javadoc导航栏组织

图2. Javadoc选项卡导航

使用JavaTOC doclet生成的Eclipse Javadoc API参考结构

图3. HTML-Kit编辑器

Eclipse Java API参考结构和TOC生成必需的文件

清单6. plug-in.xml

清单7. plug-in.xml

清单8. doclet.toc.xml

清单9. org.dita.dost.index.toc.xml

告示

“简单是效率的灵魂”。 —奥斯汀·弗里曼

结论

发布评论取消回复

最近发表

热门文章

标签列表

java8api参考文档_Java API参考文档

背景

构建易于使用且可搜索的Java API参考文档

考虑的方法

关于Javadoc和JavaTOC doclet

使用标准Javadoc工具生成的Eclipse Javadoc API参考结构

图1. Javadoc API引用结构

清单1. plug-in.xml

清单2. MANIFEST.MF

清单3. plug-in.xml

清单4. plugin.properties

清单5. doclet.toc.xml

标准Javadoc导航栏组织

图2. Javadoc选项卡导航

使用JavaTOC doclet生成的Eclipse Javadoc API参考结构

图3. HTML-Kit编辑器

Eclipse Java API参考结构和TOC生成必需的文件

清单6. plug-in.xml

清单7. plug-in.xml

清单8. doclet.toc.xml

清单9. org.dita.dost.index.toc.xml

告示

“简单是效率的灵魂”。 —奥斯汀·弗里曼

结论

相关文章

发布评论取消回复

最近发表

热门文章

标签列表