java8api参考⽂档_JavaAPI参考⽂档
java8api参考⽂档
背景
改善产品⽂档的适⽤性是许多项⽬成功的关键。 成功与否直接归因于您努⼒⽣成和编写良好的⽂档。
本资料假定您熟悉Java软件，Java API参考⽂档结构，Javadoc⽣成，并且想进⼀步了解如何提供改进的Java API参考⽂档。
对于初学者，您应该熟悉以下这些：
Javadoc，由Sun Microsystems创建的开源⼯具。 有关更多信息，请阅读 。
JavaHelp，⼀个具有索引和搜索功能的帮助集。 有关更多信息，请参见 。
JavaHelp中的创作⼯具。 有关更多信息，请参考上的列表java修改html文件
标准Java编码约定
Javadoc约定。 有关详细信息，请参见 。
构建易于使⽤且可搜索的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专业化结合使⽤的J
avaTOC 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参考⽰例 ）使⽤的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引⽤结构
该屏幕截图显⽰了Javadoc API引⽤结构
<的扩展点将其标识为帮助系统的插件。
清单1. l
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="1.0"?>
<plugin>
<extension point="">
< toc file="l" 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: lipse.ui,
Eclipse-AutoStart: true
要么
清单3. l
<?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="">
< toc file="l" 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
清单5. l
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE=""?>
<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选项卡导航
该屏幕截图显⽰了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编辑器
该屏幕截图显⽰了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. l
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="1.0"?>
<plugin>
<extension point="">
<toc file="l" primary="true"/>
</extension>
</plugin>
以下清单显⽰了Eclipse Java API参考插件的相同⽰例，该插件基于Java包结构参考了多个TOC XML⽂件。 查看⽂档时，使⽤⼀个TOC 或多个TOC XML⽂件⽅法没有什么区别。
清单7. l
<?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="">
<toc file="l" primary="true"/>
<toc file="org.l"/>
<toc file="org.dita.l"/>
<toc file="org.dita.l"/>
<toc file="org.dita.l"/>
<toc file="org.l"/>
<toc file="org.dita.l"/>
<toc file="org.dita.l"/>
<toc file="org.l"/>
<toc file="org.dita.l"/>
<toc file="org.dita.l"/>
</extension>
</plugin>
您可以使⽤navref和anchor元素，以及map元素的anchorref属性，以在Eclipse输出中⽣成集成点，在该输出中，导航⽂件会在运⾏时被拉⼊或附加到⾃⾝。 请参阅Eclipse参考资料，以获取有关编写Eclipse导航⽂件的更多信息。
清单8. l

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。