注释不参与代码编译和运行。当计算机执行带有注释的语句时,它将跳过该语句并执行以下语句
有注释语句。
一般来说,它描述和解释用人类语言编写的代码,以便让他人和自己更好地理解自己
编写的程序。
API(Application Programming Interface,应用程序编程接口)抽象上说是软件系统不同组成
部分的衔接约定。通俗上来讲就是人们写了一段代码,然后我们想要在别的地方使用这段代
码,于是给这段代码定义了一个名字(API),我们在别的地方使用这个名字(API),就相当
于运行了整段代码(对于API这里仅作简单介绍,对其特性定义阐述的也很不全面。如果想要
深入了解可以自行查阅资料)。
(1)注释
在Java中,注释有三种:
// 单行注释 将单行注释符后一整行的内容声明为注释,只能注释一行。
/*………*/ 多行注释 将多行注释符中间的部分声明为注释。可以在注释符中注释多行。
/**…….*/ 文档注释 一般使用于变量,方法,接口以及类本身的前面。作用一是解释注释后的
语句块的作用;二是便于生成Java API文档(其中的概念后面文章会一一介绍,现在可以先不
做深入了解)。
文档注释的使用为:
在要添加注释的语句块(语句块的本质就是一段代码)的上一行敲下/**接着按回车(Enter)
键,这样就能生成一个相应语句块的文档注释。
你可以在其中填写其对应的语句块(main方法)的解释。
其中@param arg 表示你可以在编写文档注释的时候添加args参数的解释。
如下:
(2)生成API文档
a.通过Eclipse生成API文档。
点击Project,选择Generate JavaDoc选项,进入如下界面。
设置Javadoc command路径为你安装jdk路径下bin文件夹下的javadoc.exe文件路径。
C:\Program Files\Java\jdk1.8.0_171\bin\javadoc.exe
勾选要生成文档的项目FFF。
接着设置文档生成级别(Create Javadoc for member with visibility )
我们设置为private ,意思是会生成项目中的全部内容的API文档。
接着是储存路径(Use standard doclet )。可以进行修改,也可以使用默认。
我们这里使用默认路径D:\test\FFF\doc
点击Finish。可以看到控制台输出生成信息。在项目结构下多出了一个doc目录。里面存放的是
文档的相关信息。
打开我的电脑,进入D:\test\FFF\doc目录下,双击index.html文件。就可以进入文档界面。
b.使用控制台命令生成API文档
首先我们在d盘的test文件夹中新建一个名为helloworld的txt文件,将注释过的helloworld程序代
码粘贴进去。
保存退出,将其修改为helloworld.java文件
在cmd界面进入test文件夹
输入 javadoc -d doc helloworld.java命令。
这条命令的意思是在当前文件夹下新建doc文件夹,并在doc文件夹中生成API文档。
注:如果命令出错一般为文本文档编码格式出现问题。
修改方式如下:网上下载一个文本编辑器。我这里使用的是Notepad++
不要使用记事本的另存为来修改编码格式。因为记事本的UTF-8格式其实是UTF-8-BOM格式。
使用记事本修改后会提示
在文本编辑器下打开helloworld.Java文件,选择编码方式为UTF-8保存退出。
在cmd界面下更改命令为
javadoc -d doc -encoding UTF-8 helloworld.java
成功导出