Java基础 | 如何用Javadoc Tool写规范正确的java注释
Posted Hdparm
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了Java基础 | 如何用Javadoc Tool写规范正确的java注释相关的知识，希望对你有一定的参考价值。
前言：如果在源代码中添加以专用的定界符/**开始的注释，那么可以很容易地生成一个具有专业水准的文档。注释应该放置在所描述特性的前面。注释以/** 开始，并以*/结束。
文档注释：
第一段：概要描述，通常用一句或者一段话简要描述该类的作用，以英文句号作为结束
第二段：详细描述，通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束
第三段：文档标注，用于标注作者、创建时间、参阅类等信息
如果文档中有到其他文件的链接，再图像文件（用户界面的组件的图表或图像等）,应该将这些文件放到子目录doc-files中。javadoc实用程序将从源目录拷贝这些目录及其中的文件到文档目录中。在链接中需要使用doc-files目录，<imgsrc=“doc-files/uml_png”alt=“UMLdiagram”>。
注释语法
Javadoc命令是用来生成自己的API文档，使用方式：
javadoc 源文件名.java
javadoc -d 文档存放目录 源文件名.java
通过IDEA生成Javadoc ： Tools -> Generate JavaDoc
Javadoc 用法格式如下：
javadoc [options] [packagenames] [sourcefiles]
其中表示的意思：
- options 表示 Javadoc 命令的选项；
- packagenames 表示包名；
- sourcefiles 表示源文件名。
类的注释：
所有的类都必须添加创建者和创建日期，类注释必须放在import语句之后，类定义之前。没有必要在每一行的开始用星号*
说明：在设置模板时，注意 IDEA 的 @author 为$USER，而 eclipse 的@author 为$user，大小写有区别，而日期
的设置统一为 yyyy/MM/dd 的格式。
代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等。
说明：代码与注释更新不同步，就像公路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了导航的意义。
方法的注释：
所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释、除了返回值、参数异常说明外，还必须指出该方法做什么事情，实现什么功能。
注意：对子类的实现要求，或者调用注意事项，请一并说明方法内部单行注释，在被注释语句上方另起一行，使用 // 注释。方法内部多行注释使用 /* */注释，注意与代码对齐。在类中删除未使用的任何字段和方法、内部类；在方法中删除未使用的参数声明与内部变量。
文档标记含义
每一个方法注释必须放在所描述的方法之前。除了通用标记之外，还可以使用下面的标记：
•@param变量描述
这个标记将对当前方法的“param”（参数）部分添加一个条目。这个描述可以占据多
行，并可以使用html标记。一个方法的所有@param标记必须放在一起。
•@return描述
这个标记将对当前方法添加“return”（返回）部分。这个描述可以跨越多行，并可以
使用HTML标记。
•©throws类描述
这个标记将添加一个注释，用于表示这个方法有可能抛出异常。
域的注释：
所有的枚举类型字段必须要有注释，说明每个数据项的用途。
注意：只需要对公有域（通常指的是静态常量）建立文档。
通用注释：
谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。
说明：代码被注释掉有两种可能性：1）后续会恢复此段代码逻辑。2）永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉即可，假如需要查阅历史代码，登录代码仓库即可。
好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的另一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释又是相当大的负担。
注意，一定要使用井号（#)，而不要使用句号（.）分隔类名与方法名，或类名与变量名。Java编译器本身可以熟练地断定句点在分隔包、子包、类、内部类与方法和变量时的不同含义。
包与概述注释：
可以直接将类、方法和变量的注释放置在Java源文件中，只要用/**. ..*/文档注释界定就可以了。
可以为所有的源文件提供一个概述性的注释。这个注释将被放置在一个名为overview,html的文件中，这个文件位于包含所有源文件的父目录中。标记<body>...</body>2间的所有文本将被抽取出来。当用户从导航栏中选择“Overview”时，就会显示出这些注释内容。
注释抽取：
- 如果是一个包，应该运行命令:
javadoc -d doc Directory nameOfPackage
- 对于多个包生成文档，运行:
javadoc -d doc Directory nameOfPackage \\nameOfPackage
- 如果文件在默认包中，就应该运行：
javadoc -d docDirectory *.java
生成非HTML格式的文档，可以提供自定义的格式命令，以便生成想要的任何输出形式
注释总结：
对于注释的要求：第一、能够准确反映设计思想和代码逻辑；第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。
参考链接：
1.https://en.wikipedia.org/wiki/Javadoc
2.https://www.oracle.com/cn/technical-resources/articles/java/javadoc-tool.html
以上是关于Java基础 | 如何用Javadoc Tool写规范正确的java注释的主要内容，如果未能解决你的问题，请参考以下文章
如何用 APT(Annotation Processing Tool)自动生成代码
如何用电脑记事本写程序？（零基础学习，之前基本不用电脑，只用手机。）