注释

细心的同学已经注意到,我们在上一节中的代码里,使用//开头的文字来描述了代码的作用,这个就是注释。注释在Java中的作用至关重要,一个好的Java代码,注释一定是非常多的,如果你没有在代码中写注释的习惯,你就要从现在开始改变这个坏习惯了。

Java注释

在Java程序中,注释是为了解释代码,方便自己和他人阅读理解代码的一段文字。

Java中的注释并不是程序中的一部分,在编译Java代码的时候,编译器会自动忽略注释。

三种注释方式

注释方式一共有三种,分别如下:

1、单行注释,以双斜线开头,直到这一行的结尾结束:

2、多行注释以/*星号开头,以*/结束,可以有多行:

3、文档注释,一种特殊的多行注释,以/**开头,以*/结束,如果有多行,每行通常以星号开头:

文档注释

上面的第三种注释,也就是文档注释,比起普通的注释来多了一个功能。

Java中有一个javadoc工具(处于$JAVA_HOME的bin目录下),该工具可以用来提取源代码中的文档注释自动转化成API文档。

我们打开IDEA,把HelloWorld改一下:

然后在控制台输入:

可以在红框内找到控制台和新增的doc文件:

img

可以在IDEA的控制台中看到这些:

img

我们可以看到项目的文件夹下多了一个doc,离开IDEA去找到项目文件夹下的doc里面的index.html(或者IDEA里直接右键doc下的index.html选择,Open in Browser),双击之后就能在网页看到我们的文档了:

img

img

javadoc用法简述

在命令行界面中(同学们,windows可以通过cmd打开,mac可以通过终端打开,但是都可以在IDEA中可以通过控制台打开)输入:

就可以看到javadoc的详细用法了。

有同学注意到,我们刚才使用了3个参数:-d,-author,-version。这三个参数是什么意思呢?我们来看看javadoc --help给出的解释:

img

IDEA图形化界面使用javadoc

在IDEA中,我们可以通过图形界面来直接使用javadoc,选择Tools——>Generate JavaDoc...,填入输出路径即可:

img

img

javadoc标签

javadoc 工具软件识别以下标签:

标签描述示例
@author标识一个类的作者@author description
@deprecated指名一个过期的类或成员@deprecated description
{@docRoot}指明当前文档根目录的路径Directory Path
@exception标志一个类抛出的异常@exception exception-name explanation
{@inheritDoc}从直接父类继承的注释Inherits a comment from the immediate surperclass.
{@link}插入一个到另一个主题的链接{@link name text}
{@linkplain}插入一个到另一个主题的链接,但是该链接显示纯文本字体Inserts an in-line link to another topic.
@param说明一个方法的参数@param parameter-name explanation
@return说明返回值类型@return explanation
@see指定一个到另一个主题的链接@see anchor
@serial说明一个序列化属性@serial description
@serialData说明通过writeObject( ) 和 writeExternal( )方法写的数据@serialData description
@serialField说明一个ObjectStreamField组件@serialField name type description
@since标记当引入一个特定的变化时@since release
@throws和 @exception标签一样.The @throws tag has the same meaning as the @exception tag.
{@value}显示常量的值,该常量必须是static属性。Displays the value of a constant, which must be a static field.
@version指定类的版本@version info
你是否感觉技术要学的内容太多?永无止境?
你是否感觉已经学会很多,但是面试就挂?
非酱油已经启动互联网“零”计划
提供1对1辅导,带你从“零”到入职
中途不经过任何弯路,最短距离拿到高薪offer
到非酱油藏经阁修炼,工资最少涨2000!