java javadoc_使用Java 9向Javadoc搜索添加术语

java javadoc

有一个相对较旧的网页,称为“ Proposed Javadoc Tags ”,最初似乎是与Javadoc 1.2一起编写的,其中列出了“ Sun有朝一日可能会在Javadoc中实现的标签”。 在此列表中的标签是@category@example@tutorial@index@exclude@todo@internal@obsolete@threadsafety 。 其中一个标签@index已从“建议标签”移至“标准标签”,并已包含在Java 9中@index Javadoc工具文档指出, @index标签用于指定索引的“搜索词或短语”可以在Java 9的新Javadoc搜索功能中进行搜索 。

JDK-4034228 (“ stddoclet:添加@index doc-comment标签以根据常用词生成索引”)的存在证明了一段时间以来一直希望能够在Javadoc生成的文档中添加用于搜索的术语的能力, JDK-4279638 (“ Javadoc注释:需要标记要包含在API索引中的单词”)和JDK-4100717 (“允许用户指定索引条目”)。 JEP 225 (“ Javadoc搜索”)用于“向标准doclet生成的API文档添加搜索框,该搜索框可用于搜索文档中的程序元素以及标记的单词和短语。”

Java 9及更高版本中的Javadoc将自动在“搜索”中包含多个构造,这些构造可从生成HTML输出中执行。 默认情况下,这些可搜索的字符串是基于方法的名称,成员的名称,类型的名称,包的名称和模块的名称的字符串。 @index提供的@index是,未内置在这些刚列出的结构的名称中的短语或搜索词可以显式地包含在搜索索引中。

在几个示例中,可以添加用于搜索Javadoc生成的文档的自定义文本的功能可能会很有用。 Javadoc工具文档引用了“特定于域的术语ulps”(“ 最后一个单位 ”),并解释说,尽管“ ulps在整个java.lang.Math类中都使用过”,但它“不会出现在任何类或方法声明名称。” 使用@index将允许Math类的API设计人员在可搜索索引中添加“ ulps ”,以帮助人们在搜索“ ulps”时找到Math类。 在有效Java的第三版中 ,乔什·布洛赫(Josh Bloch)引用了另一个可能在其中使用Javadoc {@index}示例。 在第56条中,Bloch引用了一个使用{@index IEEE 754} (“ IEEE浮点算法标准 ”)的示例。

我最近在JDK中遇到了一个案例,我认为使用{@index}是合适的。 我最近在Dual-Pivot Quicksort上发布了文章,但意识到在搜索Javadoc生成的输出时,找不到与该术语匹配的任何内容。 通过{@index}在Javadoc搜索索引中添加“ Dual Pivot Quicksort”和“ Mergesort”之类的词似乎很有用。

不幸的是,在{@index }标记中嵌入文本中的空格似乎只会导致第一个空格之前的术语出现在呈现HTML中(并且是唯一可以搜索的部分)。 为了证明这一点,以下可笑的Java代码包含三个{@index} Javadoc标记,它们代表刚刚讨论的三个示例。

文档中使用{@index}的Java代码

package dustin.examples.javadoc;/*** Used to demonstrate use of JDK 9's Javadoc tool* "@index" tag.*/
public class JavadocIndexDemonstrator
{/*** This method complies with the {@index IEEE 754} standard.*/public void doEffectiveJava3Example(){}/*** Accuracy of the floating-point Math methods is measured in* terms of {@index ulps}, "units in the last place."*/public void doMathUlpsExample(){}/*** This method uses a version of the {@index Dual-Pivot Quicksort}.*/public void doDualPivotQuicksort(){}
}

当在Java 9.0.4的Windows 10计算机上针对上述代码执行Javadoc工具时,生成HTML页面如下所示:

方法文档中在“ IEEE”之后生成HTML中缺少“ 754”,在“ Dual-Pivot”之后缺少“ Quicksort”。 下一个代码清单显示了这些文本缺少的生成HTML源代码。

HTML来源

<div class="block">This method uses a version of the <a id="Dual-Pivot" class="searchTagResult">Dual-Pivot</a>.</div>. . .
<div class="block">This method complies with the <a id="IEEE" class="searchTagResult">IEEE</a> standard.</div>

从刚刚显示HTML输出中,很明显为什么只有第一个空格之前的文本才出现在页面中并且可以搜索。 与每个可搜索条目的“ searchTagResult”类相关联的“ id”属性由可搜索字符串组成。 因为HTML“ id”属性不能有空格 ,所以“ id”值只能使用第一个空格之前的字符。

由于“ id”属性中不允许使用空格,因此在处理单个短语中需要搜索的多个单词时,需要使用以下变通方法之一。

  1. 删除空格
    • “ {@index IEEE 754}”成为“ {@index IEEE754}”
    • “ {@index Dual-PivotQuicksort}”变为“ {@index Dual-PivotQuicksort}”
  2. 用允许的字符替换空格(例如,连字符)
    • “ {@index IEEE 754}”成为“ {@index IEEE-754}”
    • “ {@index Dual-Pivot-Quicksort}”变为“ {@index Dual-Pivot-Quicksort}”
  3. 为词组中的每个单词使用单独的{@index}
    • “ {@index IEEE 754}”成为“ {@index IEEE} {@index 754}”
    • “ {@index Dual-Pivot Quicksort}”变为“ {@index Dual-Pivot} {@index Quicksort}”
  4. 仅在词组中最重要的词上使用{@index}
    • “ {@index Dual-Pivot}快速排序”变为“ {@index Dual-Pivot}快速排序”
  5. 用常见的单个单词表示法表示多个单词短语
    • 这就是Javadoc工具文档中的“ ulps”效果好而不是“最后一个单元”效果好的原因。

JEP 225的“动机”部分(“ Javadoc搜索”)很好地总结了这种在Javadoc中搜索术语的功能的好处:


如果您还不熟悉标准doclet的布局,那么很难浏览它们。 可以使用外部搜索引擎,但这可能会导致页面过时或不相关。 可以使用浏览器的内置搜索功能,但仅限于在当前页面内搜索,而不是整个文档中的内容。

尽管在Java 9中向Javadoc生成的文档添加搜索功能是次要的功能,但是它可以用于使自己的Java代码的文档对其他开发人员和该代码的用户更加有用。

翻译自: https://www.javacodegeeks.com/2018/01/adding-terms-javadoc-search-java-9.html

java javadoc

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/334304.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

oracle system用户创建job 其他用户,oracle创建表空间、用户和表以及sys和system的区别...

一、oracle的3个内置账号(口令管理)scott(示范账户) tiger 内置账号system 系统管理员 操作用户sys 超级管理员 操作数据conn system/sasa;show user登录超级用户conn a/b as sysdba 或者 sysopera/b任何账号密码都可以(只能在服务端(安装数据的电脑)上运行更改用户密码&#x…

浅析 Linux 初始化系统(系统服务管理和控制程序/Init System) -- systemd

文章目录一、Systemd 的简介和特点&#xff08;一&#xff09;同 SysVinit 和 LSB init scripts 兼容&#xff08;二&#xff09;更快的启动速度&#xff08;三&#xff09;systemd 提供按需启动能力&#xff08;四&#xff09;Systemd 采用 Linux 的 Cgroup 特性跟踪和管理进程…

查询 service monitor 时发生内部错误_通过Service访问应用 (1)

目录通过Service访问应用通过Pod IP访问应用 通过ClusterIP Service在集群内部访问 通过Service访问应用通过之前的操作&#xff0c;应用部署完成了&#xff0c;我们的Demo网站已经成功启动了&#xff0c;那么如何访问网站呢&#xff1f;通过Pod IP访问应用我们可以通过Pod IP来…

jdk 8 时区 转换_使用JDK 8将收藏转换为地图

jdk 8 时区 转换我多次遇到这样的情况&#xff0c;希望将多个对象存储在Map中而不是Set或List中&#xff0c;因为将唯一标识信息的Map应用于对象有一些优势 。 Java 8通过流和Collectors.toMap&#xff08;…&#xff09;方法使翻译变得比以往更加容易。 使用Map而不是Set的一…

开源备份软件 oracle,oracle备份和恢复

最好把所有表删掉重新导入&#xff0c;表字段改变不会还原出来 &#xff0c;只会还原数据1 将数据库TEST完全导出,用户名system 密码manager 导出到D:\daochu.dmp中exp system/managerTest filed:\DB_backup\GWAMQA_Oracle\GWAM_Dev_201410311059.dmp fully2 将数据库中system用…

c语言 方程改main的值_C语言编程笔记丨编写第一个C语言程序hello world,我教你哇...

如果用C语言输出&#xff1a;Hello&#xff0c;world&#xff01;&#xff0c;该如何编写程序&#xff1f;**代码如下&#xff1a;**#include//包含标准库的信息main()//定义名为main的函数&#xff0c;不接受参数值{//main函数的语句都放在花括号中&#xff0c;也表示函数体的…

iPhone 手机/苹果手机如何设置来电铃声?

文章目录方法一、使用 APP 库乐队设置方法二、使用第三方软件「爱思助手」设置方法一、使用 APP 库乐队设置 详见《iPhone 手机设置铃声简易教程》 方法二、使用第三方软件「爱思助手」设置 详见《苹果 iPhone 手机怎么设置铃声》

linux定时创建文件,linux下如何创建定时任务

文/PM回忆录本篇文章不详细讲述cron服务的那种配置文件&#xff0c;只是应用层面的讲解&#xff0c;只求初步的掌握。说到定时任务&#xff0c;不能不介绍下cron&#xff1a;一、cron定时任务是什么在LINUX中&#xff0c;周期执行的任务一般由cron这个守护进程来处理[ps -ef|gr…

连接堡垒机出现java环境_Java 8:长期支持的堡垒

连接堡垒机出现java环境斯蒂芬科尔本 &#xff08; Stephen Colebourne &#xff09;的文章“ Java 9可以使用六个星期 ”开始&#xff0c;“ Java 9仅仅六个星期就已经过时了。” Colebourne参考了Mark Reinhold博客文章“ Moving Java Forwarding Faster ”&#xff0c;并写道…

assertj断言异常_编写自定义的AssertJ断言

assertj断言异常AssertJ是广泛使用的Hamcrest匹配器的替代匹配库。 实际上&#xff0c;对于我自己的项目&#xff0c;我已经更改为仅使用AssertJ-我只是发现流畅的界面和可扩展性非常吸引人。 您可以编写自定义断言&#xff0c;如下所示&#xff1a; 想象一下一种具有强度和饮…

Unix 发展简史

1965年时&#xff0c;贝尔实验室&#xff08;Bell Labs&#xff09;加入一项由通用电气&#xff08;General Electric&#xff09;和麻省理工学院&#xff08;MIT&#xff09;合作的项目&#xff1b;该项目要建立一套多使用者、多任务、多层次&#xff08;multi-user、multi-ta…

linux服务器不会中毒,[转载]ubuntu 不会中毒的原因(转)

ubuntu不会中毒的原因不是因为linux用户少&#xff0c;而是其它原因。如下是转载的高手的文章&#xff1a;可能不少人持这样一种观点&#xff0c;认 为 Linux病毒少是因为Linux不像Windows那么普及&#xff0c;其实这种观点很早已经被人批驳过了&#xff0c;一个最有力的论据是…

6-7 使用函数输出水仙花数_「Java」再议printf函数

System.out.printf() 是在JDK1.5版开始引入的方法&#xff0c;即在JDK1.5以后的版本才可以使用此函数&#xff0c;printf 方法有 printf(String format, Object ... args) 和 printf(Locale l, String format, Object ... args) 两种重载方式。其实学过C语言的小伙伴应该会觉得…

Debian GNU/Linux 的发展简史

Debian 是最早的 Linux 发行版之一&#xff0c;由 Ian Murdock&#xff08;伊恩默多克&#xff09; 创立。lan Murdock 于1973年4 月28日出生于德国的君斯坦市(Konstanz, Germany)。他是Debian GNU/Linux 发行版的创始人&#xff0c;也是商用Linux发行商Progeny公司的创始人。他…

jdk 细粒度锁_使用JDK 8轻松进行细粒度排序

jdk 细粒度锁Java的8的推出流和有用的静态 / 默认的方法比较接口可以很容易地根据个人的领域两个对象比较“值&#xff0c;而不需要实现一个比较&#xff08;T&#xff0c;T&#xff09;在其对象的类方法被比较。 我将使用一个简单的Song类来帮助演示这一点&#xff0c;接下来…

c语言命名规则_C语言的基本数据类型及变量

学习目标了解C语言的基本数据类型了解变量的基本概念了解变量的使用方法了解了变量的命名方法了解格式占位符了解变量的输出了解C语言程序的基本数据类型及概念的使用方法擦在C语言编程中&#xff0c;系统定义了多种数据类型&#xff0c;本节将讲解基本数据类型的分类。基本数据…

linux socket默认超时时间设置,Socket中如何设置连接超时 (转)

Socket中如何设置连接超时 (转)Socket中如何设置连接超时AntGhazi/2001.12.14 主页&#xff1a;antghazi.yeah把CSDN与中文翻了底朝天&#xff0c;也没找到如何设置socket的连接超时的满意方法&#xff0c;问此问题的兄弟已有一大堆&#xff0c;这里偶就讲一下win下如何设置soc…

Linux 常用的软件包管理器/软件包管理工具详解

文章目录RPM 是什么&#xff1f;应用于哪些系统RPM 的前端工具有哪些RPM 包命名规范RPM 安装软件的默认路径RPM 安装原理图RPM 命令详解YUM 是什么&#xff1f;应用于哪些系统YUM 原理说明主要特点YUM 和 RPM 的区别YUM 命令详解DNF 是什么应用于哪些系统DNF 命令详解APT 是什么…

java world_Java World中的GraphQL简介

java world许多人认为GraphQL仅适用于前端和JavaScript&#xff0c;它在Java等后端技术中不占优势&#xff0c;但事实确实如此。 还经常将GraphQL与REST进行比较&#xff0c;但是这种比较是否合理&#xff1f; 首先&#xff0c;让我开始回答其中最重要的问题。 什么是GraphQL…

快速排序 动图_Java十大排序算法最强总结

看到一篇很不错的文章&#xff0c;不多说&#xff0c;看吧排序算法说明0.1 排序的定义对一序列对象根据某个关键字进行排序。0.2 术语说明稳定&#xff1a;如果a原本在b前面&#xff0c;而ab&#xff0c;排序之后a仍然在b的前面&#xff1b;不稳定&#xff1a;如果a原本在b的前…