Java从入门到入门(III)注释和API文档生成

注释不参与代码编译和运行。当计算机执行带有注释的语句时,它将跳过该语句并执行以下语句

有注释语句。

一般来说,它描述和解释用人类语言编写的代码,以便让他人和自己更好地理解自己

编写的程序。

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

成功导出

资源下载: