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”属性中不允许使用空格,因此在处理单个短语中需要搜索的多个单词时,需要使用以下变通方法之一。
- 删除空格
- “ {@index IEEE 754}”成为“ {@index IEEE754}”
- “ {@index Dual-PivotQuicksort}”变为“ {@index Dual-PivotQuicksort}”
- 用允许的字符替换空格(例如,连字符)
- “ {@index IEEE 754}”成为“ {@index IEEE-754}”
- “ {@index Dual-Pivot-Quicksort}”变为“ {@index Dual-Pivot-Quicksort}”
- 为词组中的每个单词使用单独的
{@index}
- “ {@index IEEE 754}”成为“ {@index IEEE} {@index 754}”
- “ {@index Dual-Pivot Quicksort}”变为“ {@index Dual-Pivot} {@index Quicksort}”
- 仅在词组中最重要的词上使用
{@index}
- “ {@index Dual-Pivot}快速排序”变为“ {@index Dual-Pivot}快速排序”
- 用常见的单个单词表示法表示多个单词短语
- 这就是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
java javadoc_使用Java 9向Javadoc搜索添加术语相关推荐
- 使用Java 9向Javadoc搜索添加术语
有一个相对较旧的网页,称为" Proposed Javadoc Tags ",最初似乎是与Javadoc 1.2一起编写的,其中列出了" Sun有朝一日可能会在Javad ...
- Java文档注释(利用javadoc生成HTML文档)
目录: 1. 在代码中使用文档注释 2. 类注释 3. 方法注释 4. 域注释 5. 通用注释 6. 包与概述注释 7. 注释的抽取 1. 在代码中使用文档注释 Java 程序员在开发的过程中,或多或 ...
- java全文搜索服务器 solr_Apache Solr采用Java开发、基于Lucene的全文搜索服务器
http://docs.spring.io/spring-data/solr/ 首先介绍一下solr: Apache Solr (读音: SOLer) 是一个开源.高性能.采用Java开发.基于Luc ...
- 电脑查看java文件的工具_everything电脑文件搜索工具
everthing电脑搜索工具 2020/7/6 电子拆解 今天跟大家介绍一款基于JAVA的电脑搜索软件,具有效率高,搜索全的优点.话不多少,先上图 图1 这是安装好的搜索界面,下面教大家怎么安装: ...
- 利用Java实现PC端的划词搜索
项目介绍 全局划词搜索,可实现PC端在任意界面(almost)选中文字后,使用快捷键快速搜索该文字,需配合Windows批处理文件使用. 软件架构 Spring Boot 软件思路 首先明确一下我的需 ...
- 网吧java安装路径,java环境变量配置
windows xp下配置JDK环境变量: 1.安装JDK,安装过程中可以自定义安装目录等信息,例如我们选择安装目录为D:/java/jdk1.5.0_08: 2.安装完成后,右击"我的电脑 ...
- 【java】关于Java NIO的一切
1.概述 概述:关于Java NIO的『一切』 建议看原文 太长了 本文译自Jakob Jenkov的Java NIO.注意,并非逐字翻译,删除了原文中碎碎念的部分,有些地方也加入了自己的理解. Ja ...
- JAVA基础总结----JAVA面试必备
java语法基础: 1,关键字:其实就是某种语言赋予了特殊含义的单词. 保留字:其实就是还没有赋予特殊含义,但是准备日后要使用过的单词. 2,标示符:其实就是在程序中自定义的名词.比如类名,变量名 ...
- Java八股整理--java基础
1.方法重写与方法重载的区别: 方法重载:是指在同一个类中的多个方法有相同的名称,但是方法签名不同,编译器能够根据方法签名决定调用哪个方法.方法签名中包含方法名和参数,而方法重载是相当于多个相同的方法 ...
最新文章
- java程序包不存在_第一章 Java语言简介
- a卡显存检测软件_科普小课堂,A卡玩家如何轻松超频?
- mysql 一对多映射_mybatis关系映射之一对多和多对一
- Xcode + cocoapods + jenkins + fastlane + git + 蒲公英自动化打包 上传
- 从 JDBC 到 Mybatis,看这篇就够了
- 如何测试W5300的内部TX/RX存储器?
- java基础----集合操作---实例----List集合的初始化
- TensorFlow 1.0已死,TensorFlow 2.0万岁
- 简单记录 Part1.1
- 观CSDN网站小Bug有感
- html5 easyui 布局,Easyui 在面板中创建复杂布局_EasyUI 插件
- 优麒麟19.1安装HP扫描仪驱动
- VLAN Tag,PVID
- echarts世界地图国家及中国城市的经纬度数组整理
- python凯撒密码流程图_凯撒移位密码加密算法的Python3.0实现方法
- LaTex关于数学公式的使用(7)--- 函数单边大括号
- 智慧停车服务器及存储系统设计,浅谈:停车场管理系统系统组成
- 如何防止服务器被攻击?
- 百度视频在Android和iOS端性能测试方法
- Tomcat和Java版本对照
热门文章
- 【学习笔记】信息学竞赛中的概率与期望小结
- 洛谷P1074:靶形数独(搜索、剪枝)
- AT2370-[AGC013D]Piling Up【dp】
- nssl1460-逛机房【bfs】
- @Resource,@Autowired,@Inject3种注入方式详解
- String、StringBuilder、StringBuffer三者执行效率
- 【Android】实现页面跳转
- 配置环境变量 path
- 2019蓝桥杯省赛---java---C---4(质数)
- 普里姆算法(修路问题)+图解