Javadoc文档标记及在IntelliJ IDEA中生成类库手册的使用详解

很多程序对Javadoc都不重视，认识不到Javadoc的作用，很多人都是这样认为的：“我只要写好功能就够了，写Javadoc太浪费时间，也没啥作用，还不如用写Javadoc的时间再多些个功能呢！”，我们知道注释是为了解释代码的作用的，是为了将来给自己或者别人快速了解代码的，在方法内一般用行注释//的比较多，是针对一小块代码做出解释的，而Javadoc的作用是针对整个方法或者整个类做一个简要的概述的，使得别人不通过看具体方法代码就能知道某个方法或者某个类的作用和功能。写了Javadoc的在别人使用到类时，将鼠标悬停到类上或者方法上，javadoc会以提示信息显示出来，这样开发者在跳进源代码中就能知道类或者方法的作用。说到这里可能还是有很多人不能认同这种观点，还是认识不到Javadoc的作用。我们看一下Spring框架，随便打开一个文件可以看到一般注释内容都要比代码量多，有的时候注释量占整个文件内容的2/3。有人还是认为Spring是大框架，每个Java项目都在用他们写的好事应该的，我们公司自己的项目就我们公司几个人看，没必要花时间去写多余的Javadoc，那你是不是该这么认为了Spring大厂中的顶尖大牛都这么做，我们小菜鸟是不是对自己要求更严格一些，向大牛去学习呢？！假如在公司A程序员写了Javadoc，B程序员只写功能不写Javadoc不写注释，那么一般会认为A程序员会比B程序员做的好。认识不到Javadoc的作用就像认识不到设计模式的作用一样，很多人都认识不到设计模式的作用，认为将简单问题复杂化，你看一下每个大框架都会用到多种设计模式，如果只知道写增删改查，再工作几年仍然不会有提高。

一：简介
Javadoc用于描述类或者方法的作用。Javadoc可以写在类上面和方法上面。

https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html

二：写在类上面的Javadoc
写在类上的文档标注一般分为三段：

第一段：概要描述，通常用一句或者一段话简要描述该类的作用，以英文句号作为结束
第二段：详细描述，通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束
第三段：文档标注，用于标注作者、创建时间、参阅类等信息
第一段：概要描述
单行示例：

1 package org.springframework.util;
2 /**
3 * Miscellaneous {@link String} utility methods.
4 * 
5 */
6 public abstract class StringUtils {

多行示例：

1 package java.lang;
2 
3 /**
4 * Class {@code Object} is the root of the class hierarchy.
5 * Every class has {@code Object} as a superclass. All objects,
6 * including arrays, implement the methods of this class.
7 */
8 public class Object {}

在注释中出现以@开头东东被称之为Javadoc文档标记，是JDK定义好的，如@author、@version、@since、@see、@link、@code、@param、@return、@exception、@throws等。

1. @link：{@link 包名.类名#方法名(参数类型)} 用于快速链接到相关代码
@link的使用语法{@link 包名.类名#方法名(参数类型)}，其中当包名在当前类中已经导入了包名可以省略，可以只是一个类名，也可以是仅仅是一个方法名，也可以是类名.方法名，使用此文档标记的类或者方法，可用通过按住Ctrl键+单击可以快速跳到相应的类或者方法上，解析成html其实就是使用< code> 包名.类名#方法名(参数类型)< /code>

 1 @link示例
 2 
 3 // 完全限定的类名
 4 {@link java.lang.Character}
 5 
 6 // 省略包名
 7 {@link String}
 8 
 9 // 省略类名，表示指向当前的某个方法
10 {@link #length()}
11 
12 // 包名.类名.方法名(参数类型)
13 {@link java.lang.String#charAt(int)}

2. @code： {@code text} 将文本标记为code
{@code text} 会被解析成<code> text </code>
将文本标记为代码样式的文本，在code内部可以使用 < 、> 等不会被解释成html标签, code标签有自己的样式

一般在Javadoc中只要涉及到类名或者方法名，都需要使用@code进行标记。

第二段：详细描述
详细描述一般用一段或者几个锻炼来详细描述类的作用，详细描述中可以使用html标签，如<p>、<pre>、<a>、<ul>、<i>等标签，通常详细描述都以段落p标签开始。
详细描述和概要描述中间通常有一个空行来分割

 1 package org.springframework.util;
 2 
 3 /**
 4 * Miscellaneous {@link String} utility methods.
 5 *
 6 * <p>Mainly for internal use within the framework; consider
 7 * <a href="http://commons.apache.org/proper/commons-lang/">Apache's Commons Lang</a>
 8 * for a more comprehensive suite of {@code String} utilities.
 9 *
10 * <p>This class delivers some simple functionality that should really be
11 * provided by the core Java {@link String} and {@link StringBuilder}
12 * classes. It also provides easy-to-use methods to convert between
13 * delimited strings, such as CSV strings, and collections and arrays.
14 *
15 */
16 public abstract class StringUtils {

一般段落都用p标签来标记，凡涉及到类名和方法名都用@code标记，凡涉及到组织的，一般用a标签提供出来链接地址。

3. @param
一般类中支持泛型时会通过@param来解释泛型的类型

1 /**
2 * @param <E> the type of elements in this list
3 */
4 public interface List<E> extends Collection<E> {}

4. @author
详细描述后面一般使用@author来标记作者，如果一个文件有多个作者来维护就标记多个@author，@author 后面可以跟作者姓名(也可以附带邮箱地址)、组织名称(也可以附带组织官网地址)

 1 // 纯文本作者
 2 @author Rod Johnson
 3 
 4 // 纯文本作者，邮件
 5 @author Igor Hersht, igorh@ca.ibm.com
 6 
 7 // 超链接邮件 纯文本作者
 8 @author <a href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a>
 9 
10 // 纯文本邮件
11 @author shane_curcuru@us.ibm.com
12 
13 // 纯文本 组织
14 @author Apache Software Foundation
15 
16 // 超链接组织地址 纯文本组织
17 @author <a href="https://jakarta.apache.org/turbine"> Apache Jakarta Turbine</a>

5. @see 另请参阅
@see 一般用于标记该类相关联的类,@see即可以用在类上，也可以用在方法上。

1 /**
2 * @see IntStream
3 * @see LongStream
4 * @see DoubleStream
5 * @see <a href="package-summary.html">java.util.stream</a>
6 * /
7 public interface Stream<T> extends BaseStream<T, Stream<T>> {}

6. @since 从以下版本开始
@since 一般用于标记文件创建时项目当时对应的版本，一般后面跟版本号，也可以跟是一个时间，表示文件当前创建的时间

1 package java.util.stream;
2 
3 /**
4 * @since 1.8
5 */
6 public interface Stream<T> extends BaseStream<T, Stream<T>> {}

1 package org.springframework.util;
2 
3 /**
4 * @since 16 April 2001
5 */
6 public abstract class StringUtils {}

7. @version 版本
@version 用于标记当前版本，默认为1.0

1 package com.sun.org.apache.xml.internal.resolver;
2 /**
3 * @version 1.0
4 */
5 public class Resolver extends Catalog {}

三：写在方法上的Javadoc
写在方法上的文档标注一般分为三段：

第一段：概要描述，通常用一句或者一段话简要描述该方法的作用，以英文句号作为结束
第二段：详细描述，通常用一段或者多段话来详细描述该方法的作用，一般每段话都以英文句号作为结束
第三段：文档标注，用于标注参数、返回值、异常、参阅等
方法详细描述上经常使用html标签来，通常都以p标签开始，而且p标签通常都是单标签，不使用结束标签，其中使用最多的就是p标签和pre标签,ul标签, i标签。

pre元素可定义预格式化的文本。被包围在pre元素中的文本通常会保留空格和换行符。而文本也会呈现为等宽字体，pre标签的一个常见应用就是用来表示计算机的源代码。

一般p经常结合pre使用，或者pre结合@code共同使用(推荐@code方式)
一般经常使用pre来举例如何使用方法

注意：pre>标签中如果有小于号、大于号、例如泛型在生产javadoc时会报错

 1 /**
 2 * Check whether the given {@code CharSequence} contains actual <em>text</em>.
 3 * <p>More specifically, this method returns {@code true} if the
 4 * {@code CharSequence} is not {@code null}, its length is greater than
 5 * 0, and it contains at least one non-whitespace character.
 6 * <p><pre class="code">
 7 * StringUtils.hasText(null) = false
 8 * StringUtils.hasText("") = false
 9 * StringUtils.hasText(" ") = false
10 * StringUtils.hasText("12345") = true
11 * StringUtils.hasText(" 12345 ") = true
12 * </pre>
13 * @param str the {@code CharSequence} to check (may be {@code null})
14 * @return {@code true} if the {@code CharSequence} is not {@code null},
15 * its length is greater than 0, and it does not contain whitespace only
16 * @see Character#isWhitespace
17 */
18 public static boolean hasText(@Nullable CharSequence str) {
19 return (str != null && str.length() > 0 && containsText(str));
20 }

1 <pre>{@code
2 Person[] men = people.stream()
3 .filter(p -> p.getGender() == MALE)
4 .toArray(Person[]::new);
5 }</pre>

8. @param
@param 后面跟参数名，再跟参数描述

1 /**
2 * @param str the {@code CharSequence} to check (may be {@code null})
3 */
4 public static boolean containsWhitespace(@Nullable CharSequence str) {}

9. @return
@return 跟返回值的描述

1 /**
2 * @return {@code true} if the {@code String} is not {@code null}, its
3 */
4 public static boolean hasText(@Nullable String str){}

10. @throws
@throws 跟异常类型异常描述 , 用于描述方法内部可能抛出的异常

1 /**
2 * @throws IllegalArgumentException when the given source contains invalid encoded sequences
3 */
4 public static String uriDecode(String source, Charset charset){}

11. @exception
用于描述方法签名throws对应的异常

1 /**
2 * @exception IllegalArgumentException if <code>key</code> is null.
3 */
4 public static Object get(String key) throws IllegalArgumentException {}

12. @see
@see既可以用来类上也可以用在方法上，表示可以参考的类或者方法

1 /**
2 * @see java.net.URLDecoder#decode(String, String)
3 */
4 public static String uriDecode(String source, Charset charset){}

13. @value
用于标注在常量上，{@value} 用于表示常量的值

1 /** 默认数量 {@value} */
2 private static final Integer QUANTITY = 1;

14. @inheritDoc
@inheritDoc用于注解在重写方法或者子类上，用于继承父类中的Javadoc

基类的文档注释被继承到了子类
子类可以再加入自己的注释（特殊化扩展）
@return @param @throws 也会被继承

四：示例
spring-core中的StringUtils 示例

 1 package org.springframework.util;
 2 
 3 /**
 4 * Miscellaneous {@link String} utility methods.
 5 *
 6 * <p>Mainly for internal use within the framework; consider
 7 * <a href="http://commons.apache.org/proper/commons-lang/">Apache's Commons Lang</a>
 8 * for a more comprehensive suite of {@code String} utilities.
 9 *
10 * <p>This class delivers some simple functionality that should really be
11 * provided by the core Java {@link String} and {@link StringBuilder}
12 * classes. It also provides easy-to-use methods to convert between
13 * delimited strings, such as CSV strings, and collections and arrays.
14 *
15 * @author Rod Johnson
16 * @author Juergen Hoeller
17 * @author Keith Donald
18 * @author Rob Harrop
19 * @author Rick Evans
20 * @author Arjen Poutsma
21 * @author Sam Brannen
22 * @author Brian Clozel
23 * @since 16 April 2001
24 */
25 public abstract class StringUtils {
26 
27 /**
28 * Decode the given encoded URI component value. Based on the following rules:
29 * <ul>
30 * <li>Alphanumeric characters {@code "a"} through {@code "z"}, {@code "A"} through {@code "Z"},
31 * and {@code "0"} through {@code "9"} stay the same.</li>
32 * <li>Special characters {@code "-"}, {@code "_"}, {@code "."}, and {@code "*"} stay the same.</li>
33 * <li>A sequence "{@code %<i>xy</i>}" is interpreted as a hexadecimal representation of the character.</li>
34 * </ul>
35 * 
36 * @param source the encoded String
37 * @param charset the character set
38 * @return the decoded value
39 * @throws IllegalArgumentException when the given source contains invalid encoded sequences
40 * @since 5.0
41 * @see java.net.URLDecoder#decode(String, String)
42 */
43 public static String uriDecode(String source, Charset charset) {} 1 package com.example.demo; 2

 3 /**
 4 * 类 {@code OrderService} 订单服务层.
 5 *
 6 * <p> 主要包括 创建订单、取消订单、查询订单等功能更
 7 *
 8 * @see Order
 9 * @author <a href="mailto:mengday.zhang@gmail.com">Mengday Zhang</a>
10 * @since 2018/5/12
11 */
12 public class OrderService {
13 
14 /** 默认数量 {@value} */
15 private static final Integer QUANTITY = 1;
16 
17 /**
18 * 创建订单.
19 *
20 * <p> 创建订单需要传用户id和商品列表(商品id和商品数量).
21 *
22 * <p><pre>{@code
23 * 演示如何使用该方法
24 * List<Goods> items = new ArrayList<>();
25 * Goods goods = new Goods(1L, BigDecimal.ONE);
26 * Goods goods2 = new Goods(2L, BigDecimal.TEN);
27 * items.add(goods);
28 * items.add(goods2);
29 *
30 * Order order1 = new Order();
31 * order.setUserId("1");
32 * order.setItems(items);
33 * OrderService#createOrder(order);
34 * }
35 * </pre>
36 *
37 * @param order 订单信息
38 * @throws NullPointerException 参数信息为空
39 * @exception IllegalArgumentException 数量不合法
40 * @return 是否创建成功
41 * @version 1.0
42 * @see {@link Order}
43 */
44 public boolean createOrder(Order order) throws IllegalArgumentException{
45 Objects.requireNonNull(order);
46 
47 List<Goods> items = order.getItems();
48 items.forEach(goods -> {
49 BigDecimal quantity = goods.getQuantity();
50 if (quantity == null || BigDecimal.ZERO.compareTo(quantity) == 0) {
51 throw new IllegalArgumentException();
52 }
53 });
54 
55 System.out.println("create order...");
56 
57 return true; }
   }

五：生成Javadoc
idea生成javadoc https://www.cnblogs.com/cyberniuniu/p/5021910.html

通过IDEA生成Javadoc： Tools --> Generate JavaDoc -->
注意要配置编码，如果不配送为生成乱码，还需要配置Output directory

在 IntelliJ IDEA 中为自己设计的类库生成 JavaDoc

因为某个项目需要，为团队其他兄弟姐妹开发了一个 XML 分析处理器，并将其设计为一个类库，提供相应的 API 接口。为了方便大家的使用，需要生成对应的 JavaDoc 帮助文档，就像 JavaSE 标准库提供的 JavaDoc 那样。我的开发工具为 IntelliJ IDEA 12.1.6，本身提供了很好的 JavaDoc 生成功能，以及标准 JavaDoc 注释转换功能，其实质是在代码编写过程中，按照标准 JavaDoc 的注释要求，为需要暴露给使用者的类、方法以及其他成员编写注释。然后使用 IDEA 的功能自动调用 javadoc.exe（JDK 自带的工具）根据源代码中的注释内容自动生成 JavaDoc 文档（超文本格式）。标准 JavaDoc 的注释规则，大家可以在网上很容易搜索到，这里有几点倒是要特别注意一下：

IDEA 的 JavaDoc 生成功能在菜单 Tools->Generate JavaDoc 项里面。
点击上述菜单项后，会出现生成 JavaDoc 的对话框，一般的选项都很直观，不必细说。但是要注意生成 JavaDoc 的源代码对象的选择，一般以模块（Module）为主，必要时可以单独选择必要的 Java 源代码文件，不推荐以 Project 为 JavaDoc 生成的源范围。
里面有一个 Locale 可选填项，表示的是需要生成的 JavaDoc 以何种语言版本展示，根据 javadoc.exe 的帮助说明，这其实对应的就是 javadoc.exe 的 -locale 参数，如果不填，默认可能是英文或者是当前操作系统的语言，既然是国人，建议在此填写 zh_CN，这样生成的 JavaDoc 就是中文版本的，当然指的是 JavaDoc 的框架中各种通用的固定显示区域都是中文的。你自己编写的注释转换的内容还是根据你注释的内容来。
还有一个“Other command line arguments:”可选填项，非常重要，是填写直接向 javadoc.exe 传递的参数内容。因为有一些重要的设置，只能通过直接参数形式向 javadoc.exe 传递。这里必须要填写如下参数：

-encoding UTF-8 -charset UTF-8 -windowtitle "你的文档在浏览器窗口标题栏显示的内容" -link http://docs.oracle.com/javase/7/docs/api
第一个参数 -encoding UTF-8 表示你的源代码（含有符合 JavaDoc 标准的注释）是基于 UTF-8 编码的，以免处理过程中出现中文等非英语字符乱码；第二个参数 -charset UTF-8 表示在处理并生成 JavaDoc 超文本时使用的字符集也是以 UTF-8 为编码，目前所有浏览器都支持 UTF-8，这样最具有通用性，支持中文非常好；第三个参数 -windowtitle 表示生成的 JavaDoc 超文本在浏览器中打开时，浏览器窗口标题栏显示的文字内容；第四个参数 -link 很重要，它表示你生成的 JavaDoc 中涉及到很多对其他外部 Java 类的引用，是使用全限定名称还是带有超链接的短名称，举个例子，我创建了一个方法 public void func(String arg)，这个方法在生成 JavaDoc 时如果不指定 -link 参数，则 JavaDoc 中对该方法的表述就会自动变为 public void func(java.lang.String arg)，因为 String 这个类对我自己实现的类来讲就是外部引用的类，虽然它是 Java 标准库的类。如果指定了 -link http://docs.oracle.com/javase/7/docs/api 参数，则 javadoc.exe 在生成 JavaDoc 时，会使用 String 这样的短名称而非全限定名称 java.lang.String，同时自动为 String 短名称生成一个超链接，指向官方 JavaSE 标准文档 http://docs.oracle.com/javase/7/docs/api 中对 String 类的详细文档地址。-link 实质上是告诉 javadoc.exe 根据提供的外部引用类的 JavaDoc 地址去找一个叫 package-list 的文本文件，在这个文本文件中包含了所有外部引用类的全限定名称，因此生成的新 JavaDoc 不必使用外部引用类的全限定名，只需要使用短名称，同时可以自动创建指向其外部引用 JavaDoc 中的详细文档超链接。每个 JavaDoc 都会在根目录下有一个 package-list 文件，包括我们自己生成的 JavaDoc。
JavaDoc 生成完毕，即可在其根目录下找到 index.html 文件，打开它就可以看到我们自己的标准 JavaDoc API 文档啦。

————————————————
版权声明：本文为CSDN博主「vbirdbest」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/vbirdbest/article/details/80296136

posted on 2020-05-27 08:56 专注30 阅读(931) 评论(0) 收藏举报

刷新页面返回顶部

Javadoc文档标记及在IntelliJ IDEA中生成类库手册的使用详解

在 IntelliJ IDEA 中为自己设计的类库生成 JavaDoc

导航

公告

Javadoc文档标记 及在IntelliJ IDEA中生成类库手册的使用详解

在 IntelliJ IDEA 中为自己设计的类库生成 JavaDoc

导航

公告

Javadoc文档标记及在IntelliJ IDEA中生成类库手册的使用详解