编写程序时，应该说必须为程序添加一些注释，用来说明某段代码的作用，或者说明某个类的用途、某个方法的功能，以及该方法的参数和返回值的数据类型及其意义等。
添加注释主要考虑以下三个方面：
- 永远不需要相信自己的理解力和记忆力，随着代码量的增加代码会越来越难阅读，添加注释实际上是添加编码当时的想法。
- 可读性第一，效率第二，横向考虑整个团队的发展，个人的代码一定会有其他人阅读的，而合适的注释是个人或者其他人阅读代码成本最低的一个途径。
- 代码即文档，其实就是说代码规范，好的代码规范下的代码可读性非常高，有一句话叫代码自解释，当代码自己能解释自己的意愿的时候可读性就有了。
代码注释分类
- 单行注释 用双斜线 ”//” 表示
- 多行注释 用 /------------------/ 表示
- 文档注释 用 /**-----------------*/ 表示【用javadoc为自己的代码生成API文档用】
public class CommentTest
{
/*
这里面的内容全部是多行注释
Java语言真的很有趣，
*/
public static void main(String[] args)
{
// 这是一行简单的注释
System.out.println("Hello World!");
// System.out.println("这行代码被注释了，将不会被编译、执行!");
}
}
- API文档用于说明类、方法、成员变量的功能，因此javadoc工具只处理文档源文件在类、接口、方法、成员变量、构造器和内部类之前d注释，忽略其他地方的注释，并且javadoc工具默认只处理以public或protected修饰的类、接口、方法、成员变量、构造器和内部类之前的文档注释
- API文档类似于产品说明书，默认只介绍暴露的供用户使用的部分。如果开发者确实想看到private修饰的内容，则在使用javadoc工具时增加-private选项即可
生成源码文件API文档
package davieyang;
/**
* Description:
* 网站: <a href='javascript:void(0)'>
public class JavadocTest
{
/**
* 简单测试成员变量
*/
protected String name;
/**
* 主方法，程序的入口
*/
public static void main(String[] args)
{
System.out.println("Hello World!");
}
}
package scc;
/**
* Description:
* 网站: <a href='javascript:void(0)'>
public class Test
{
/**
* 简单测试成员变量
*/
public int age;
/**
* Test类的测试构造器
*/
public Test()
{
}
}
package NBwang;
/**
* Description:
* 网站: <a href='javascript:void(0)'>
public class JavadocTagTest
{
/**
* 一个得到打招呼字符串的方法。
* @param name 该参数指定向谁打招呼。
* @return 返回打招呼的字符串。
*/
public String hello(String name)
{
return name + "，你好！";
}
}
javadoc -d apidoc -windowtitle 测试javadoc -doctitle 学习javdoc工具测试API文档 -header 我醉欲眠卿且去 *Test.java
- -d 指定生成API文档在本地的存储路径
- -windowtitle: 指定一个字符串，设置API文档的浏览器窗口标题
- -doctitle: 指定一个HTML格式的文本，用于指定概述页面标题
- -header: 指定一个HTML格式的文本，包含每个页的页眉
- 除此之外还可以使用javadoc -help来查看大量的javadoc选项
javadoc -d apidoc -windowtitle 测试 -doctitle 学习javadoc -header davieyang页眉 -version -author *Test.java
生成package的API文档
<!DOCTYPE html>
<html>
<head>
<meta name="author" content="davieyang.D.Y(davieyang.blog.csdn.net)" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title> davieyang包描述 </title>
</head>
<body>
davieyang包描述
</body>
</html>
<!DOCTYPE html>
<html>
<head>
<meta name="author" content="scc.D.Y(davieyang.blog.csdn.net)" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title> scc包描述 </title>
</head>
<body>
scc包描述
</body>
</html>
javadoc -d apidoc -windowtitle 测试 -doctitle 学习 javadoc工具 -header davieyang页眉 -version -author davieyang scc
![Java小案例——随机数猜测随机数猜测[图]](data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=)