使用Java 9向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搜索功能中进行搜索 。

添加的条款的Javadoc生成的文档中搜索的能力已被期望用于这表现在存在一些时间JDK-4034228 (“stddoclet:添加@index DOC-注释标记,用于产生从公共字索引”), 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

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

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

相关文章

Java学习、简单代码编译

【2.1】求明天是星期几 public class study { public static void main(String args[]) { short i7; short tomorrow,yesterday; tomorrow (short) ((i1) % 7); yesterday (short)((i-17) % 7); System.out.print(“tomorrow:”tomorrow" “”\n"); System.out.pr…

Java学习:类的封装、继承和多态

【3.1】声明日期类及使用日期对象 public class MyDate{ //类声明 int year,month,day; //成员变量&#xff0c;表示年月日 void set(int y,int m,int d) //成员方法、设计日期值 { yeary; monthm; dayd; } void set(MyDate d) //将当前对象值设置为参数值&#xff0c;重载 { …

同步器 java_您可能不知道的五个高级Java同步器

同步器 java除了基于每个Java对象具有的锁定位的通用同步外&#xff0c;您还可以使用Java中更复杂的同步器&#xff0c;例如&#xff1a; 信号量 –使用许可的概念表示一个位置中允许的最大线程数。 当使用值1时&#xff0c;其行为类似于同步&#xff0c;也称为二进制信号量。…

Java语言学习概述

md:创建新的文件夹 上面这行作用&#xff1a;将name&#xff1a;Tom,age12写入到文件1.doc中&#xff0c;也就是说先建个文档&#xff0c;再把这句话写进去。 del *.txt 作用&#xff1a;删除以txt结尾的所有文件 rd team2 作用&#xff1a;删除team2文件夹&#xff08;且这…

在CDI应用程序中使用@Alternative

在许多情况下&#xff0c;您可能希望拥有一个以上版本的Bean&#xff0c;并将其用于不同的目的。 备用bean的典型理由是出于测试目的&#xff0c;其中备用bean提供模拟数据。 为了获得实时数据&#xff0c;“真实” bean必须连接到的实时系统的好处是远程&#xff0c;或者在测试…

小狐狸ChatGPT付费创作系统 前端对话提示undefined index:temperature解决方法

很多会员使用着ChatGPT付费创作系统&#xff0c;特别是新安装系统后前端输入对话时提示错误undefined index:temperature&#xff0c;检查了反代、检查了KEY均正常&#xff0c;这问题主要是因为后台设置里新用户免费送对话次数为空&#xff0c;没设置赠送次数原因&#xff0c;导…

第二章 Java基本语法(一)

本文主要内容&#xff1a; 关键字、标识符、变量、类型转换、进制转换、运算符 一、关键字 二、标识符 比如&#xff1a;类名&#xff0c;变量名&#xff0c;方法名&#xff0c;接口名&#xff0c;包名。。。 小技巧&#xff1a;直接在我的电脑输入cmd&#xff0c;就可以打开…

第二章 Java基本语法(二)

本文主要内容&#xff1a; 运算符、if-else、switch-case 一、位运算符 运算符之五&#xff1a;位运算符 每左移一位&#xff0c;相当于是在原来的基础上乘2. int i 21; System.out.println(“i<<2:”(i<<2)); 输出&#xff1a;i<<2:84 结论&#xff1a; …

java 断点_每个Java开发人员应拥有的持久断点

java 断点当开发人员使用Java进行工作时&#xff0c;即使您尝试调试其他内容&#xff0c;也总是会遇到一些失败的情况。 这是应该在每个IDE中启用的持久断点的列表。 &#xff08;恕我直言&#xff09; 是的&#xff0c;从理论上讲&#xff0c;您应该能够从良好的日志记录实现…

第二章 Java基本语法(三)

本文主要内容&#xff1a; 循环结构、特殊关键字break和continue的使用&#xff0c;质数问题的优化 循环结构&#xff1a;Boolean类型 程序编写&#xff1a; 从键盘输入两个正整数m和n&#xff0c;找出他们的最大公约数和最小公倍数。 import java.util.Scanner; public clas…

用Priam设置Cassandra

前面已经解释了如何在AWS中设置Cassandra 。 所描述的设置有效&#xff0c;但在某些情况下可能还不够。 例如&#xff0c;它不能为您提供制作和还原备份的简便方法&#xff0c;添加新节点依赖于自定义python脚本&#xff0c;该脚本会随机选择一个种子。 因此&#xff0c;现在我…

Matlab入门(一)

MATLAB学习笔记 本系列主要内容来源&#xff1a;matlab官方付费课程的学习笔记 截图较多&#xff0c;之后更新会尽量增加文字说明 matlab简单常用的命令 数组 round:四舍五入函数。

MATLAB入门(二)

可以使用 plot 函数在一张图上绘制两个相同长度的向量。 plot(x,y)plot 函数接受一个附加参数。使用该参数&#xff0c;您可以通过在引号中包含不同符号的方式来指定与之对应的颜色、线型和标记样式。 plot(x,y,"r--o")以上命令将会绘制一条红色 虚线 (–)&#x…

Spring @Lazy批注用例

Spring框架几乎可以毫不费力地为您解决许多常见的编程问题&#xff0c;但是它的某些功能比其他功能鲜为人知。 在本文中&#xff0c;我们将仔细研究属于该组的Lazy批注。 阅读了几个示例之后&#xff0c;您应该能够将注释应用于日常开发任务。 1. 懒豆初始化 Spring的默认行为…

MATLAB入门(三)

求平均值 两种方法生成列向量 读取文件 将数据保存到小数点后两位 result round(M,2);将矩阵中的每个元素都三次方 x3 x.^3将矩阵中的数据按照升序排序 sort(data)创建一个行变量计算每一个列变量的平均值 avg mean(data)diff函数 Y diff(X) 计算沿大小不等于 1…

Java学习 第三章 数组(一)一维数组

第三章 数组 3-1 数组的概述 数组&#xff1a;多个相同类型数据按一定的顺序排列的集合&#xff0c;并使用一个名字命名&#xff0c;并通过编号的方式对这些数据进行统一管理。 数组相关概念&#xff1a; 数组名、下标&#xff08;索引、角标&#xff09;、元素、数组的长度 数…

mapreduce 算法_MapReduce算法–了解数据联接第1部分

mapreduce 算法在本文中&#xff0c;我们继续执行一系列实现算法的系列&#xff0c;该算法在使用MapReduce进行数据密集型文本处理中找到&#xff0c;这一次讨论数据联接。 虽然我们将讨论在Hadoop中联接数据的技术并提供示例代码&#xff0c;但在大多数情况下&#xff0c;您可…

几个有用的word小技巧,保准提升效率~

这几天改报告改到头秃。年底了&#xff0c;实验室各种项目在结项&#xff0c;作为一名研一新生&#xff0c;理所应当地承担起了体力活的工作。主要负责项目报告的研究背景调研、报告汇总、格式调整等。 格式调整&#xff0c;看起来非常简单的一项工作&#xff0c;却是最费时费…

Java 8:长期支持的堡垒

斯蒂芬科尔本 &#xff08; Stephen Colebourne &#xff09;的文章“ Java 9可以使用六个星期 ”开始&#xff0c;“ Java 9仅仅六个星期 就已过时。” Colebourne参考了Mark Reinhold博客文章“ Moving Java Forwarding Faster ”&#xff0c;并写道&#xff1a;“新的Java发…

我的2020(年终总结)

我的2020 2020对每个人来说可能都是极不平凡的一年&#xff0c;对我尤其是。这一年我整个的人心境发生了极大的变化。总结来说&#xff0c;有这么几件大事&#xff1a;复试、毕设、大学毕业、研究生开学、分手、再脱单、疫情在家。今天坐在实验室也不知道该干点什么&#xff0…