java基础学习（四）：注释和javadoc使用

最新推荐文章于 2021-10-06 14:52:01 发布

Auraros

最新推荐文章于 2021-10-06 14:52:01 发布

阅读量296

点赞数

分类专栏： Java 文章标签： java 注释和javadoc javadoc API文档生成 java的API文档生成

本文链接：https://blog.csdn.net/qq_43634001/article/details/105749412

版权

Java 专栏收录该内容

13 篇文章 0 订阅

订阅专栏

Java语言是一门强类型语言。强类型包含两方面的含义：（1）所有的变量必须先声明、后使用。（2）指定类型的变量只能接受类型与之匹配的值。强类型语言可以在编译过程中发现源代码的错误，从而保证程序更加健壮。

4.1 注释

！！！记住，一定要多写注释

4.1.1 单行注释

public class Commentest
{
	//单行注释
	public static void main(string[] args)
	{
		//单行注释输出
		System.out.println("Hello World");
	}
}

4.1.2 多行注释

public class Commentest
{
	/*
	多行注释
	哈哈哈
	*/
	public static void main(string[] args)
	{
		System.out.println("Hello World");
	}
}

注释不仅可以给人思路，还可以debug，把语句注释，运行看看是不是这个语句所产生的错误。

4.1.3 Java 9 增强文档注释

相信单行注释，多行注释大家听过了。但Java还有这一种更加牛逼额的注释：文档注释。如果编写Java源代码时添加了合适的文档注释，然后JDK提供的javadoc工具可以直接将源代码里的文档注释提取成一份系统的API文档。
API文档是啥?其实就是在你开发一个大型号的软件的时候，要定义几千几万各类，这时候是不是需要一份说明文档，用于说明每个类、每个方法的用途。当其他人使用一个类或一个方法时，他无须关心这个类或方法的具体实现，他只要知道这个类或方法的功能即可，然后使用这个这个类或方法来实现具体目的，也就是通过调用应用程序接口(API)来编程。API文档就是用以说明这些应用程序接口的文档。
大家可以到Java的官方网站去下载API文档。这里我就不写了，网上博客特别多。下载好后点打开/docs/api 路径下，打开index.html 即可。长相大概如下图所示。

在这里插入图片描述
好像已经到了Java14去了，太快了，具体api文档的内容我也不是特别了解，等我以后稍微了解之后再来写一写。
同样，在开发中定义类、方法时也可以添加文档注释，然后使用javadoc工具来生成自己API文档。
问题来了，API文档重不重要？
毫无疑问，API是Java提供的基本编程接口，当使用Java语言进行编程时，不可能把所有的Java类、所有方法都记下来，当编程遇到不会的地方，就可以查找。所以，查看API文档的方法是学习Java的一个最基本的技能。
文档注释以斜线后紧跟两个星号(/**)开始，以星号后紧跟一个斜线(*/)结束，中间部分全部都是文档注释，会被提到API文档中。
例如，下面先编写一个JavadocTest类，这个类里包含了对类、方法、成员变量的文档注释。

下面我们来尝试一下：

(一):编写一个 JavadocTest.java类：

package lee;
/**
 * Description:
 * 网站：<a href="https://blog.csdn.net/qq_43634001/article/details/105702218">Java语言概述与开发</a><br>
 * Copyright (C), 2020, Li Weile<br>
 * This program is testing the funtion of javadoc. <br>
 * Program Name: test_javadoc <br>
 * Date: 2020-04-25 <br>
 * @author LiWeile 664006035@qq.com
 * @version 1.0
 */
public class JavadocTest
{
	/**
	 * 简单测试成员变量
	 */
	protected String name;
	
	/**
	 * 主方法：程序的入口
	 */
	public static void main(String[] args)
	{
		System.out.println("Hello World!");
	}
}

（二）：编写一个 Test.java

package yeeku;
/**
 * Description:
 * 网站：<a href="https://blog.csdn.net/qq_43634001/article/details/105702218">Java语言概述与开发</a><br>
 * Copyright (C), 2020, Li Weile<br>
 * This program is testing the funtion of javadoc. <br>
 * Program Name: test_javadoc <br>
 * Date: 2020-04-25 <br>
 * @author LiWeile 664006035@qq.com
 * @version 1.0
 */
public class Test
{
	/**
	 * 简单测试成员变量
	 */
	public int age;
	/**
	 * Test 类的测试构造器
	 */
	public Test()
	{
	}
}

（三）输入javadoc命令

javadoc -d apidoc -windowtitle Test -doctitle learnJavadocTestAPIdocument -header my_class *Test.java

这里一定要主意好空格，书里面的有点印刷问题，会报错。可以看到如下输出，点开自己写的包：
在这里插入图片描述

这样就可以看到自己的API文档了，是有点儿牛逼的亚子。

javadoc命令的基本用法如下：

javadoc 选项 Java 源文件|包

javadoc命令可对源文件、包生成API文档，在上面的语法格式中，Java源文件可以支持通配符，例如：使用 *.java 来代表当前路径下所有的Java源文件。Javadoc的常用选项有如下几个：

-d ：该选项指定一个路径，用于将生成的API文档放到指定目录下
windowtitle :该选项指定一个字符串，用于设置API文档的浏览器窗口标题
doctitle：该选项指定一个HTML格式的文本，用于指定概述页面的标题。（注意：只有对处于多个包下的源文件来生成API文档时，才有概述页面）
header:该选项指定一个HTML格式的文本，包含每个页面的页眉。
除此之外，javadoc命令还包含了大量其他选项，读者可以通过在命令行窗口执行javadoc -help 来查看javadoc 命令的所有选项。

除此之外，如果希望javadoc工具生成更详细的文档信息，例如为方法参数、方法返回值等生成详细的说明信息，则可利用javadoc标记。常用的javadoc标记如下：

@author：指定Java程序的作者
@version：指定源文件的版本
@deprecated：不推荐使用的方法
@param：方法的参数说明信息
@return：方法的返回值说明信息
@see：“参见”，用于指定交叉参考的内容
@exception：抛出异常的类型
@throws：抛出的异常和@exception同义。
需要指出的是：这些标记的使用是有位置限制的。上面这些标记可以出现在类或者接口文档注释中的有@see、@deprecated、@author、@version 等；可以出现在方法或构造器文档注释中的有@see、@deprecated、@param、@return、@throws、和@exception等。可以出现在成员变量的文档注释中有@see和@deprecated等。
我们再写一个文件，包含一个hello方法，该方法的文档注释使用了@param和@return等文档标记。文件名叫JavadocTagTest.java

package yeeku;
/**
 * Description:
 * 网站：<a href="https://blog.csdn.net/qq_43634001/article/details/105702218">Java语言概述与开发</a><br>
 * Copyright (C), 2020, Li Weile<br>
 * This program is testing the funtion of javadoc. <br>
 * Program Name: test_javadoc <br>
 * Date: 2020-04-25 <br>
 * @author LiWeile 664006035@qq.com
 * @version 1.0
 */
public class JavadocTagTest
{
	/**
	 * 一个得到打招呼字符串的方法
	 * @param name 该参数指定向谁打招呼
	 * @return 返回打招呼的字符串
	 */
	
	public String hello(String name)
	{
		return name + ",你好!";
	}
}

上面程序中粗体字标识出使用javadoc标记的示范，再次使用javadoc工具来生成API文档，这次为了能够提取到文档中的@author 和@version 等标记信息，再使用javadoc 工具时增加-author 和 -version两个选项，即按如下格式来运行：

javadoc -d apidoc -windowtitle 测试 -doctitle 学习 javadoc 工具c的测试API文档 -header 我的类 -version -author *Test.java

可以看到：
在这里插入图片描述
接下来还是使用上面编写的三个java文件，但是把三个Java文件按包结构分开组织存放，并提供对应的包描述文件，源文件和对应包描述文件的组织结构如下：

lee 文件夹：包含JavadocTest.java 文件（该Java类的包为lee），对应描述包文件package.html
yeeku 文件夹：包含Test.java 文件和JavadocTagTest.java 文件（这两个Java类的包为yeeku），对应包描述文件package.html
在命令行窗口进入lee和yeeku所在路径（package路径），执行如下：

javadoc -d apidoc -windowtitle 测试 -doctitle 学习javadoc工具的测试API文档 -header 我的类 -version -author lee yeeku

上面的命令指对lee包和yeeku包来生成API文档，而不是对Java源文件来生成API文档，这也是允许的。其中lee包和yeeku包下面都提供对应的包描述文件。打开页面：

在这里插入图片描述

通常稍微大一点的软件目录一般都需要用最后这种API文档生成的方法。记住即可。

Auraros

关注

0
点赞
踩
2

收藏

觉得还不错? 一键收藏
0
评论
java基础学习（四）：注释和javadoc使用

Java语言是一门强类型语言。强类型包含两方面的含义：（1）所有的变量必须先声明、后使用。（2）指定类型的变量只能接受类型与之匹配的值。强类型语言可以在编译过程中发现源代码的错误，从而保证程序更加健壮。4.1 注释！！！记住，一定要多写注释4.1.1 单行注释public class Commentest{ //单行注释 public static void main(str...
复制链接

扫一扫