网站制作的管理,低多边形网站,临夏州住房与建设局官方网站,哪里不好就去建设文章目录命令简介命令选项中文乱码javadoc 命令实例进入源代码文件所在目录#xff0c;解析指定的源代码文件#xff0c;生成 API 文档解析指定包下的所有源码文件#xff0c;生成 API 文档指定源文件根目录#xff0c;再指定具体的包路径#xff0c;解析其中的源码文件解析指定的源代码文件生成 API 文档解析指定包下的所有源码文件生成 API 文档指定源文件根目录再指定具体的包路径解析其中的源码文件生成 API 文档指定多个源文件根目录再指定多个包路径解析其中的源码文件生成 API 文档解析具体路径所指定的源代码文件生成 API 文档指定源文件的根目录再指定包路径递归遍历所有的子包解析其中的源文件生成 API 文档文档注释格式规范简要概述关于类/接口的概要描述关于方法的概要描述详细描述关于类的详细描述关于方法的详细描述注释中的 HTML 标签注释示例代码文档注解顺序可多次使用的注解文档注解versionsinceauthorseelinkplainlinkdeprecatedparamreturnthrowsexceptionvaluecodedocRootinheritDocliteralserialserialData命令简介
javadoc 是 Sun 公司提供的一个技术JDK 的 bin 目录下你可以看到命令执行文件 javadoc它从程序源代码中抽取注释内容形成一个和源代码配套的 API 帮助文档。也就是说只要在编写程序时以一套特定的标签作注释在程序编写完成后通过 Javadoc 就可以同时形成程序的开发文档了。
javadoc 命令只能提取源代码文件中的文档注释标记 /**...*/ 内的内容。文档注释内可以包含普通文本HTML 标记和 JavaDoc 标记这些内容构成 JavaDoc 文档。
在实现时javadoc 依赖于 java 编译器完成其工作。javadoc 会调用 javac 编译类、方法、变量的声明部分而忽略它们的实现部分。javadoc 会建立类的内容丰富的内部表示包括类层次和“使用”关系并读取源文件中文档注释的内容解析注释中的注解最后生成 HTML 格式的说明文档。
实际上javadoc 将在不带方法体的纯 stub 文件的 .java 源文件上运行。这意味着可以创建 API 的最早期版本在编写任何代码之前就可编写文档注释并运行 javadoc。
依赖编译器可以确保 HTML 输出完全对应于实际实现这些实现可能有赖于隐式的而非显式的源代码。例如javadoc 将建立在 .class 文件中存在但在源代码中不存在的缺省构造方法Java 语言规范的第 8.6.7 节的文档。
当 javadoc 建立其内部文档结构时它将加载所有引用的类。由于这一点javadoc 必须能查找到所有引用的类包括引导类、扩展类和用户类。有关详细信息参见如何查找类。一般而言所创建的类必须加载为扩展或位于 javadoc 的类路径中。
官方文档 JDK1.7 Linux 系统环境下 https://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html JDK1.7 Windows 系统环境下 https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html JDK1.8 Unix 系统环境下 https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html JDK1.8 Windows 系统环境下 https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html
命令选项
查看命令使用说明
C:\Users\fxbjavadoc -help
用法: javadoc [options] [packagenames] [sourcefiles] [files]-overview file 从 HTML 文件读取概览文档-public 仅显示 public 类和成员-protected 显示 protected/public 类和成员 (默认值)-package 显示 package/protected/public 类和成员-private 显示所有类和成员-help 显示命令行选项并退出-doclet class 通过替代 doclet 生成输出-docletpath path 指定查找 doclet 类文件的位置-sourcepath pathlist 指定查找源文件的位置-classpath pathlist 指定查找用户类文件的位置-cp pathlist 指定查找用户类文件的位置-exclude pkglist 指定要排除的程序包列表-subpackages subpkglist 指定要递归加载的子程序包-breakiterator 计算带有 BreakIterator 的第一个语句-bootclasspath pathlist 覆盖由引导类加载器所加载的类文件的位置-source release 提供与指定发行版的源兼容性-extdirs dirlist 覆盖所安装扩展的位置-verbose 输出有关 Javadoc 正在执行的操作的信息-locale name 要使用的区域设置, 例如 en_US 或 en_US_WIN-encoding name 源文件编码名称-quiet 不显示状态消息-Jflag 直接将 flag 传递到运行时系统-X 输出非标准选项的提要
通过标准 doclet 提供:-d directory 输出文件的目标目录-use 创建类和程序包用法页面-version 包含 version 段-author 包含 author 段-docfilessubdirs 递归复制文档文件子目录-splitindex 将索引分为每个字母对应一个文件-windowtitle text 文档的浏览器窗口标题-doctitle html-code 包含概览页面的标题-header html-code 包含每个页面的页眉文本-footer html-code 包含每个页面的页脚文本-top html-code 包含每个页面的顶部文本-bottom html-code 包含每个页面的底部文本-link url 创建指向位于 url 的 javadoc 输出的链接-linkoffline url url2 利用位于 url2 的程序包列表链接至位于 ur
的文档-excludedocfilessubdir name1:.. 排除具有给定名称的所有文档文件子目录。-group name p1:p2.. 在概览页面中, 将指定的程序包分组-nocomment 不生成说明和标记, 只生成声明。-nodeprecated 不包含 deprecated 信息-noqualifier name1:name2:... 输出中不包括指定限定符的列表。-nosince 不包含 since 信息-notimestamp 不包含隐藏时间戳-nodeprecatedlist 不生成已过时的列表-notree 不生成类分层结构-noindex 不生成索引-nohelp 不生成帮助链接-nonavbar 不生成导航栏-serialwarn 生成有关 serial 标记的警告-tag name:locations:header 指定单个参数定制标记-taglet 要注册的 Taglet 的全限定名称-tagletpath Taglet 的路径-charset charset 用于跨平台查看生成的文档的字符集。-helpfile file 包含帮助链接所链接到的文件-linksource 以 HTML 格式生成源文件-sourcetab tab length 指定源中每个制表符占据的空格数-keywords 使程序包, 类和成员信息附带 HTML 元标记-stylesheetfile path 用于更改生成文档的样式的文件-docencoding name 指定输出的字符编码命令的语法格式 javadoc [option] [packagenames] [sourcefiles][fileName]
option命令选项 packagenames一系列包的名字包与包之间用空格隔开例如java.lang java.lang.reflect java.awt。必须分别指定想要为之建立文档的每个包javadoc 不会递归处理子包另外也不支持使用通配符。 sourcefiles一系列源文件名使用空格分隔。可以混合包名和源文件名例如java.awt /home/src/java/awt/Graphics*.java java.lang.String。 fileName当需要指定的文件太多时可以使用 fileName 来简化fileName 是一个文件名该文件需要在当前工作目录下文件中输入源文件的路径路径之间可以使用空格分隔或者换行分隔。当然你也可以在文件中指定多个包路径同样路径之间可以使用空格分隔或者换行分隔
选项说明-public仅为public访问级别的类及类的成员生成javaDoc文档-proteceted这是默认选项仅为public和protected访问级别的类及类的成员生成javadoc文档不包含私有和默认访问级别的类和相关的成员-package仅为public,protected和默认访问级别的类及类的成员生成javaDoc文档不包含私有访问级别的类和相关的成员-private为public,protected,默认和private访问级别的类及类的成员生成javadoc文档即显示所有的类和成员-version解析version标记-author解析author标记-header-footer-bottom-splitindex将索引分为每个字母对应一个索引文件似乎这样的索引文件查询体验会更好-sourcepath 指定源文件的路径只有指定包路径例如priv.lwx.javaprac.javadoc时才需要使用该选项如果省略该选项javadoc 默认会在 classpath 指定的路径下查找源文件-classpath 指定classpath一般是指你写的类引用了其它类而这些外部类所在路径没有在环境变量classpath中可以通过此选项来设置Unix下多个路径之间使用冒号分隔Windows下使用分号分隔-d 指定javaDoc文档的输出目录
中文乱码
生成的文档中如果中文无法正常显示可以尝试在命令中使用以下选项
设置源码编码方式-encoding UTF-8 指定输出的字符编码-charset UTF-8 要使用的语言环境-locale zh_CN
javadoc 命令实例
进入源代码文件所在目录解析指定的源代码文件生成 API 文档
例如你先进入 Bus.java 的所在目录后再执行下面的命令语句
javadoc -d /Users/liaowenxiong/desktop/api -author -version Bus.java这条命令编译一个名为 Bus.java 的 Java 源文件并将生成的文档存放在目录 /Users/liaowenxiong/desktop/api指定了选项 author 表示会提取类注释中的作者姓名但是不会提取方法注释中的作者姓名选项 version 表示会提取版本的信息 。 解析指定包下的所有源码文件生成 API 文档
你要先进入 Source Root 目录下一般是指 src 目录下然后再执行下方的命令语句
javadoc -d /Users/liaowenxiong/desktop/test/api -version -author priv.liaowenxiong.javaprac.javadoc注子包的源码文件不会被解析
指定源文件根目录再指定具体的包路径解析其中的源码文件生成 API 文档
以下这种方式你无需进入 Source Root 目录下
javadoc -d /Users/liaowenxiong/desktop/test/api -sourcepath /Users/liaowenxiong/documents/IdeaProjects/java-practise/javadoc/src priv.lwx.javaprac.javadoc上述的命令语句你可以运行在任意目录下。因为通过 -sourcepath 指明了顶层包的位置以及要生成的文档的包。 注子包的源码文件不会被解析
指定多个源文件根目录再指定多个包路径解析其中的源码文件生成 API 文档
你还可以指定多个源文件的根目录
javadoc -d /Users/liaowenxiong/desktop/test/api -sourcepath /Users/liaowenxiong/documents/IdeaProjects/java-practise/javadoc/src:/Users/liaowenxiong/documents/IdeaProjects/java-practise/interface/src priv.lwx.javaprac.javadoc priv.lwx.javaprac.inter注 1.多个目录之间使用冒号分隔Windows 系统下则使用分号分隔包路径之间使用空格分隔。 2.子包的源码文件不会被解析
解析具体路径所指定的源代码文件生成 API 文档
例如进入到项目根目录下后以相对路径指定两个源码文件解析生成 API 文档命令语句如下
liaowenongdeair:java-practise liaowenxiong$ javadoc -d /Users/liaowenxiong/desktop/test/api -version -author javadoc/src/priv/liaowenxiong/javaprac/javadoc/Bus.java javadoc/src/priv/liaowenxiong/javaprac/javadoc/Person.java注意无法直接指定目录路径提示
liaowenongdeair:java-practise liaowenxiong$ javadoc -d /Users/liaowenxiong/desktop/test/api -version -author javadoc/src/priv/liaowenxiong/javaprac/javadoc
javadoc: 错误 - 非法的程序包名称: javadoc/src/priv/liaowenxiong/javaprac/javadoc指定源文件的根目录再指定包路径递归遍历所有的子包解析其中的源文件生成 API 文档
使用 -subpackages 指定包javadoc 会递归遍历其中所有的子包
javadoc -d /Users/liaowenxiong/desktop/test/api -sourcepath /Users/liaowenxiong/documents/IdeaProjects/java-practise/javadoc/src -subpackages priv -exclude priv.liaowenxiong.javaprac.javadoc.test:priv.liaowenxiong.javaprac.javadoc.demojavadoc -d /Users/liaowenxiong/desktop/test/api -sourcepath /Users/liaowenxiong/documents/IdeaProjects/java-practise/javadoc/src -subpackages priv注 1./Users/liaowenxiong/documents/IdeaProjects/java-practise/javadoc/src 这一串就是 Source Root 。 2.priv 这是 Source Root 下的顶级包 3.-exclude 指定要排除的程序包列表多个包直接使用冒号 : 分割 4.如果想要对其它包树也进行遍历则只需要在 -subpackages 的参数上附加上即可例如priv:javax:org.xml.sax
文档注释格式规范
一般分为三段
第一段概要描述通常用一句或者一段话简要描述该类的作用以英文句号作为结束 第二段详细描述通常用一段或者多段话来详细描述该类的作用一般每段话都以英文句号作为结束 第三段文档注解如果是类注释则标注作者、版本、创建时间、参阅类等信息如果是方法则标注作者、参数、返回值、异常、参阅等信息
注注释文本中的第一个英文句点 . 之前的描述文本默认是简述部分的内容一个英文句点之后的文本内容则会出现在详细描述部分。
示例如下
/*** Person类的简述* pPerson类的详细说明第一行br* Person类的详细说明第二行* author liaowenxiong* see Bus*/注 1.凡涉及到类名和方法名都用 code 标记凡涉及到组织的一般用 a 标签指明官方网址。 2.如果注释中含有指向项目中的某个文件例如图片的链接地址需要将文件存放在名为 doc-files 的目录中。
简要概述
关于类/接口的概要描述
单行示例
package org.springframework.util;
/*** Miscellaneous {link String} utility methods.* */
public abstract class StringUtils {多行示例
package java.lang;/*** Class {code Object} is the root of the class hierarchy.* Every class has {code Object} as a superclass. All objects,* including arrays, implement the methods of this class.*/
public class Object {}
关于方法的概要描述
略
详细描述
关于类的详细描述
详细描述一般用一段或者几个段落来详细描述类的作用详细描述中可以使用 html 标签如 p、pre、a、ul、i 等标签 通常详细描述都以段落 p 标签开始。
详细描述和概要描述中间通常有一个空行来分割。
package org.springframework.util;/*** Miscellaneous {link String} utility methods.** pMainly for internal use within the framework; consider* a hrefhttp://commons.apache.org/proper/commons-lang/Apaches Commons Lang/a* for a more comprehensive suite of {code String} utilities.** pThis class delivers some simple functionality that should really be* provided by the core Java {link String} and {link StringBuilder}* classes. It also provides easy-to-use methods to convert between* delimited strings, such as CSV strings, and collections and arrays.**/
public abstract class StringUtils {
关于方法的详细描述
略
注释中的 HTML 标签
方法详细描述上经常使用 html 标签来通常都以 p 标签开始而且 p 标签通常都是单标签不使用结束标签其中使用最多的就是 p 标签和 pre 标签ul 标签i 标签。
pre 标签可定义预格式化的文本。被包围在 pre 标签中的文本通常会保留空格和换行符。而文本也会呈现为等宽字体pre 标签的一个常见应用就是用来表示计算机的源代码。
一般 p 经常结合 pre 使用或者 pre 结合 code 共同使用。
注意pre 标签中如果有小于号、大于号例如泛型在生成 javadoc 时会报错。
/*** Check whether the given {code CharSequence} contains actual emtext/em.* pMore specifically, this method returns {code true} if the* {code CharSequence} is not {code null}, its length is greater than* 0, and it contains at least one non-whitespace character.* ppre classcode* StringUtils.hasText(null) false* StringUtils.hasText() false* StringUtils.hasText( ) false* StringUtils.hasText(12345) true* StringUtils.hasText( 12345 ) true* /pre* param str the {code CharSequence} to check (may be {code null})* return {code true} if the {code CharSequence} is not {code null},* its length is greater than 0, and it does not contain whitespace only* see Character#isWhitespace*/
public static boolean hasText(Nullable CharSequence str) {return (str ! null str.length() 0 containsText(str));
}经常会使用 pre 标签来举例说明如何使用方法
pre{codePerson[] men people.stream().filter(p - p.getGender() MALE).toArray(Person[]::new);
}/pre注释示例代码
package priv.liaowenxiong.javaprac.javadoc;/*** 这是一个汽车类* p汽车类说明第一行br* 汽车类说明第二行p* See also {link #measureAverageSpeed(double, int)} br* See also {link #maxSpeed} br* See also {link Person} br* See also {link Person#eat()} br* See also {link Person#sing(String)} br* author liaowenxiongbr张学友* version 1.0* see #averageSpeed* see Person* see Person#eat()*/
public class Bus {/*** 用来表示汽车行驶过程中的最大车速** author liaowenxiong* see #averageSpeed*/public double maxSpeed;/*** 用来表示汽车行驶过程中的平均车速*/public double averageSpeed;/*** 用来表示汽车行驶过程中的水温*/public float waterTemperature;/*** 用来表示天气的温度*/public float temperature;public Bus() {}/*** param distance 行驶路程单位公里km* param time 行驶时间单位小时h* return double类型 速度km/h* author liaowenxiong123*/public double measureAverageSpeed(double distance, int time) {double averageSpeed distance / time;return averageSpeed;}/*** return double类型 速度km/h* author liaowenxiong123*/public double measureMaxSpeed() {return 0;}
}示例二
package org.springframework.util;/*** Miscellaneous {link String} utility methods.** pMainly for internal use within the framework; consider* a hrefhttp://commons.apache.org/proper/commons-lang/Apaches Commons Lang/a* for a more comprehensive suite of {code String} utilities.** pThis class delivers some simple functionality that should really be* provided by the core Java {link String} and {link StringBuilder}* classes. It also provides easy-to-use methods to convert between* delimited strings, such as CSV strings, and collections and arrays.** author Rod Johnson* author Juergen Hoeller* author Keith Donald* author Rob Harrop* author Rick Evans* author Arjen Poutsma* author Sam Brannen* author Brian Clozel* since 16 April 2001*/
public abstract class StringUtils {/*** Decode the given encoded URI component value. Based on the following rules:* ul* liAlphanumeric characters {code a} through {code z}, {code A} through {code Z},* and {code 0} through {code 9} stay the same./li* liSpecial characters {code -}, {code _}, {code .}, and {code *} stay the same./li* liA sequence {code %ixy/i} is interpreted as a hexadecimal representation of the character./li* /ul* * param source the encoded String* param charset the character set* return the decoded value* throws IllegalArgumentException when the given source contains invalid encoded sequences* since 5.0* see java.net.URLDecoder#decode(String, String)*/public static String uriDecode(String source, Charset charset) {}示例三
package com.example.demo;/*** 类 {code OrderService} 订单服务层.** p 主要包括 创建订单、取消订单、查询订单等功能更** see Order* author a hrefmailto:mengday.zhanggmail.comMengday Zhang/a* since 2018/5/12*/
public class OrderService {/** 默认数量 {value} */private static final Integer QUANTITY 1;/*** 创建订单.** p 创建订单需要传用户id和商品列表(商品id和商品数量).** ppre{code* 演示如何使用该方法* ListGoods items new ArrayList();* Goods goods new Goods(1L, BigDecimal.ONE);* Goods goods2 new Goods(2L, BigDecimal.TEN);* items.add(goods);* items.add(goods2);** Order order1 new Order();* order.setUserId(1);* order.setItems(items);* OrderService#createOrder(order);* }* /pre** param order 订单信息* throws NullPointerException 参数信息为空* exception IllegalArgumentException 数量不合法* return 是否创建成功* version 1.0* see Order*/public boolean createOrder(Order order) throws IllegalArgumentException{Objects.requireNonNull(order);ListGoods items order.getItems();items.forEach(goods - {BigDecimal quantity goods.getQuantity();if (quantity null || BigDecimal.ZERO.compareTo(quantity) 0) {throw new IllegalArgumentException();}});System.out.println(create order...);return true;}
}
文档注解顺序
标记的顺序Order of Tags
author (classes and interfaces only, required)
version (classes and interfaces only, required. See footnote 1)
param (methods and constructors only)
return (methods only)
exception (throws is a synonym added in Javadoc 1.2)
see
since
serial (or serialField or serialData)
deprecated (see How and When To Deprecate APIs)可多次使用的注解
可以多次使用标记Ordering Multiple Tags
author 标记应按时间顺序排列并用逗号分隔。
param 标记应该在参数声明的顺序列出这使它更容易在视觉上与声明相匹配的列表。
throws 标记 (类同 exception)应按字母顺序列出的例外的名字。
see 标记遵循由近到远参数由少到多由上到下的顺序。
// see 标记
see #field
see #Constructor(Type, Type...)
see #Constructor(Type id, Type id...)
see #method(Type, Type,...)
see #method(Type id, Type, id...)
see Class
see Class#field
see Class#Constructor(Type, Type...)
see Class#Constructor(Type id, Type id)
see Class#method(Type, Type,...)
see Class#method(Type id, Type id,...)
see package.Class
see package.Class#field
see package.Class#Constructor(Type, Type...)
see package.Class#Constructor(Type id, Type id)
see package.Class#method(Type, Type,...)
see package.Class#method(Type id, Type, id)
see package文档注解
xxx这玩意叫法真多有人说是标签有人说是标记有人说是标注有人说是注解…
version
指定版本信息只能写一个多写的也只会提取第一个 version。
since
指定最早出现在哪个 JDK 版本
package java.util.stream;/**
* since 1.8
*/
public interface StreamT extends BaseStreamT, StreamT {}也可以跟是一个时间表示文件当前创建的时间
package org.springframework.util;/**
* since 16 April 2001
*/
public abstract class StringUtils {}
author
指定作者可以指定多个作者
author liaowenxiong
author zhangxueyou上述这样写生成的文档中作者名称之间是以逗号隔开的想分行显示作者可以写成
author liaowenxiongbrzhangxueyou更多范例
// 作者名称
author Rod Johnson// 作者、邮箱
author Igor Hersht, igorhca.ibm.com// 作者名称带超链接邮箱地址
author a hrefmailto:ovidiucup.hp.comOvidiu Predescu/a// 邮件
author shane_curcuruus.ibm.com// 组织名称
author Apache Software Foundation// 组织名称带组织网址超链接
author a hrefhttps://jakarta.apache.org/turbine Apache Jakarta Turbine/asee
生成参考其它 javaDoc 文档的链接跳至其它 javaDoc 文档或文档中的某个部位。
语法有以下几种
1.see 类名 [链接名称] 会生成一个链接点击链接会跳至指定类的首页。 例如
/**
* see priv.liaowenxiong.javaprac.javadoc.Bus 汽车类
* see Person
* /1.1类名 如果这个类在当前类有导入即 import 语句包含这个类或者在当前类同一个包下那么可以只写类名如果没有则要写全路径类名
1.2链接名称 可以指定链接名称上面例子中“汽车类”就是链接名称生成对应链接时名称就显示“汽车类”不写链接名称默认显示 priv.liaowenxiong.javaprac.javadoc.Bus。
2.see #变量名 [链接名称] 生成一个链接点击此链接跳至指定变量处。 没有指定类名默认是当前类会跳至本类指定的变量处。 变量只要写变量名即可例如
/**
* see name
* /2.1链接名称 同样可以指定链接名称例如see name 姓名链接名称就会显示“姓名”不写链接名称就直接显示 name。
3.see #方法 [链接名称] 生成一个链接点击此链接会跳至指定的方法处。 没有指定类名默认是当前类会跳至本类指定的方法处。 例如
/**
* see add(int, int)
* /3.1方法签名 方法需要写方法名和参数类型列表没有参数也要写小括号例如see show()。
4.see 类名#方法名 [链接名称] 生成一个链接点击此链接会跳至指定的其它类的指定方法处。
示例一
/**
* see Person#add(int, int)
* /示例二
/**
* see java.net.URLDecoder#decode(String, String)
*/
public static String uriDecode(String source, Charset charset){}4.1类名 如果这个类在当前类有导入则直接写类名即可如果没有则要写全路径类名。
5.see 类名#变量名 [链接名称] 生成一个链接点击此链接会跳至指定的其它类的指定变量处。 例如
/**
*
* see Person#skinColor
* /5.1类名 如果这个类在当前类有导入则直接写类名即可如果没有则要写全路径类名。
6.可以指定包名
/**
* see a hrefpackage-summary.htmljava.util.stream/a
*/7.可以指定纯文本不含链接
/**
* see Person
*/如上加上双引号只会在 See also【另请参阅】下显示文字 Person无法点击跳转。
linkplain
语法{linkplain package.class#member label} 作用与{link}相同除了链接的标签以纯文本显示而不是以代码字体显示当标签是纯文本时很有用。
link
生成内联链接它和 see 标记的区别在于 link 标记能够嵌入到注释语句中其在使用的地方产生超链接而不是在See Also列表中生成。
/**
* Use the {link #getComponentAt(int, int) getComponentAt} method.
* /
* Javadoc 会将其转换为如下代码
Use the a hrefComponent.html#getComponentAt(int, int)getComponentAt/a method.另外 link 和 {linkplain} 类似只是 link 是代码字体格式而 {linkplain} 是纯文本字体格式。 1.跳至当前类中的指定方法 语法格式 {link #方法名(参数类型) [链接名称]}
例如
/*** See also {link #measureAverageSpeed(double, int) measureAverageSpeed} */1.1链接名称 链接名称可以省略那么链接名称就显示方法名和参数
2.跳至当前类中的指定变量处 语法格式 {link #变量名 [链接名称]}
例如
/**
* See also {link #maxSpeed}
* /2.1链接名称 可以指定链接名称不指定则显示变量名
3.跳至指定的其它类首页 语法格式 {link 类名 [链接名称]}
例如
/*** See also {link priv.liaowenxiong.javaprac.javadoc.Person}*/3.1类名 如果在当前类的同一个包下或者当前类有导入此类则直接写类名即可否则需要写全路径类名
3.2链接名称 可以指定自定义的链接名称不指定则显示类名
4.跳至指定的其它类的指定变量处 语法格式 {link 类名#变量名 [链接名称]}
例如
/*** See also {link Person#skinColor 肤色}*/4.1类名 如果在当前类的同一个包下或者当前类有导入此类则直接写类名即可否则需要写全路径类名
4.2链接名称 可以指定自定义的链接名称不指定则显示“类名.变量名”
5.跳至指定的其它类的指定方法处
语法格式 {link 类名#方法名(参数类型) [链接名称]}
例如
/*** See also {link Person#eat() eat()}* See also {link Person#sing(String)}*/5.1类名 如果在当前类的同一个包下或者当前类有导入此类则直接写类名即可否则需要写全路径类名
5.2链接名称 可以指定自定义的链接名称如果不指定则会显示“类名.方法签名”例如Person.sing(String)
deprecated
用来标明被标记的类变量或方法已过时不提倡使用类名/方法名上会有一个划去的横杠。
语法 deprecated deprecated-text
针对1.2及之后版本
/*** deprecated As of JDK 1.1, replaced by* {link #setBounds(int,int,int,int)}*/针对1.1版本
/*** deprecated As of JDK 1.1, replaced by setBounds* see #setBounds(int,int,int,int)*/param
语法param parameter-name description 作用对方法中的参数进行说明我们应该针对方法的每一个参数都使用一个该标记。
描述方法的参数必须要有文字描述否则生成文档时会提示“警告: param 没有说明”
示例
/**
* param str the {code CharSequence} to check (may be {code null})
*/
public static boolean containsWhitespace(Nullable CharSequence str) {}一般类中支持泛型时会通过 param 来解释泛型的类型
/**
* param E the type of elements in this list
*/
public interface ListE extends CollectionE {}return
语法return description
描述方法的返回值如果没有返回值不要加上这个注解生成文档时会提示“错误: return 的用法无效”
示例
/**
* return {code true} if the {code String} is not {code null}, its
*/
public static boolean hasText(Nullable String str){}throws
语法 throws class-name description
指明方法可能抛出的异常必须文字描述抛出异常的原因否则生成文档时会提示“ 警告: throws 没有说明”。 如果会抛出多个异常需要写多个此注解。
示例一
/**
* throws ArrayIndexOutOfBoundsException 可能抛出数组索引越界异常
* author liaowenxiong123
*/示例二
/**
* throws IllegalArgumentException when the given source contains invalid encoded sequences
*/
public static String uriDecode(String source, Charset charset){}exception
这个注解已经被 throws 取代了同样表示可能抛出的异常不论是编译时异常还是运行时异常
/**
* exception IllegalArgumentException if codekey/code is null.
*/
public static Object get(String key) throws IllegalArgumentException {}
value
用于标注在常量上{value} 用于表示常量的值
语法格式 {value package.class#field}
当在常量字段的注释中使用 {value} 时(没有任何参数)它将显示该常量的值
/*** The value of this constant is {value}.*/
public static final String SCRIPT_START script;/** 默认数量 {value} */
private static final Integer QUANTITY 1;当在任何 doc 注释中与参数 package.class#field 字段一起使用时它将显示指定常量的值
/*** Evaluates the script starting with {value #SCRIPT_START}.*/
public String evalScript(String script) {
}code
声明其中的内容是代码注释。 将文本标记为代码样式的文本在 code 标签内部可以使用 、 等不会被解释成 html 标签code 标签有自己的样式但是样式效果不明显。所以使用的时候必须借助 html 标签 pre否则样式是无法保留的。
语法格式 {code text}
生成文档时{code text} 会被解析成 code text /code
使用方式 pre{code代码}/pre
docRoot
代表生成文档的根目录。
语法格式 {docRoot}
例如在注释中的用法如下
/**
* See the a href{docRoot}/copyright.htmlCopyright/a.
*/另请参阅 {docRoot}
inheritDoc
语法格式 {inheritDoc}
inheritDoc 用于注解在重写方法或者子类上用于继承父类中的Javadoc。 基类的文档注释被继承到了子类子类可以再加入自己的注释特殊化扩展。 return param throws 也会被继承。
literal
显示文本而不将文本解析为HTML标记或嵌套的Javadoc标记。
语法 {literal text}
例如
/**
*
* {literal ApC}
* /上面的文本 ABC 会原样显示出来而不会把 p 解释为段落标记。
serial
用于默认可序列化字段的doc注释中。
语法格式 serial field-description | include | exclude
field-description 应该解释字段的含义并列出可接受的值。
include和exclude参数标识是否应将 类 或 包 包括在序列化窗体页中或将其排除在序列化窗体页之外。如下
public 或 protected 类继承了Serializable 则是 included 除非类(或者包) 标记为 serial exclude.
private 或 package-private 类继承了Serializable 则是excluded除非类(或者包) 标记为serial include.
注意类级别的serial标记覆盖包级别的serial标记。
serialData
语法serialField field-name field-type field-description
