Java注释(包含javadoc工具的使用)

1、Java注释的种类

       我们经常使用的Java注释有三种：

       1)：单行注释

例如：//这是一个单行注释

       2)：多行注释

例如：/*  这是一个多行注释  */

    /*  这是多行注释，这是多行注释，这是多行注释，

这是多行注释，这是多行注释，这是多行注释，*/

       3)：文档注释

               例如:

/**

* @author Jack

* @version 3.2

*/

2、文档注释以及Javadoc工具的讲解

文档注释（又叫：说明注释）允许你在程序中嵌入关于程序的信息，比如：版本、作者、方法的返回值等等。

你可以使用Javadoc工具软件来生成信息，并输出到对应的HTML文件中。文档注释，使你更加方面的记录你的程序的信息。

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

javadoc输出什么

Javadoc工具将你Java程序的源代码作为输入，输出一些包含你程序注释的HTML文件。

每一个类的信息将在独自的HTML文件里。javadoc也可以输出继承的树形结构和索引。

由于javadoc的实现不同，工作也可能不同，你需要检查你的Java开发系统的版本等细节，选择合适的Javadoc版本。

实例

下面是一个使用文档注释的实例：

经过javadoc处理，Square类的注释将在Square.html中看到。

package Thread;
import java.io.*;
/**
* This class demonstrates documentation comments.
* @author Ayan Amhed
* @version 1.2
*/
public class Square {
   /**
   * This method returns the square of num.
   * This is a multiline description. You can use
   * as many lines as you like.
   * @param num The value to be squared.
   * @return num squared.
   */
   public double square(double num) {
      return num * num;
   }
   /**
   * This method inputs a number from the user.
   * @return The value input as a double.
   * @exception IOException On input error.
   * @see IOException
   */
   public double getNumber() throws IOException {
      InputStreamReader isr = new InputStreamReader(System.in);
      BufferedReader inData = new BufferedReader(isr);
      String str;
      str = inData.readLine();
      return (new Double(str)).doubleValue();
   }
   /**
   * This method demonstrates square().
   * @param args Unused.
   * @exception IOException On input error.
   * @see IOException
   */
   public static void main(String args[]) throws IOException
   {
      Square ob = new Square();
      double val;
      System.out.println("Enter value to be squared: ");
      val = ob.getNumber();
      val = ob.square(val);
      System.out.println("Squared value is " + val);
   }
}

如下，使用javadoc工具处理Square.java文件：

命令：javadoc -d d:/doc -version -author Square.java

生成的结果：

目录：

1：

2：

打开目录的Html的结果：

1：

2：

3.javadoc命令详解

上述使用了：javadoc -d d:/doc -version -author Square.java

javadoc在命令行中的用法是：

　　javadoc [选项] [软件包名称] [源文件] [@file]

Eclipse生成JavaDoc：

javadoc.exe是自动生成java文档的小工具，利用这个文档，可以很容易的了解整个工程、包、类的情况。

当然，如果你注释做的很到位的话，对于自己，还是其他想要阅读你的程序的人来说，都是一件很享受的事情。
在eclipse上使用有三个常见的入口：
　　（1）File —> Export —> java —> javadoc
　　（2）Project —> Generate Javadoc
　　（3）在工程上右键 —> Export —> java —> javadoc
　　三个入口殊途而同归，进入javadoc generation界面。

之后你必须要做的事情有：Configure，即找到javadoc.exe的路径，在java安装路径下。

选择要生成 javadoc的工程，选择你要输出的位置，默认输出到工程下的doc文件夹下面。

之后的步骤都是可选的，这里有一个要说明的问题：字符集。

　　在Extra javadoc option中可以设置：
　　-encoding UTF-8     //-encoding charsetName 是指源文件编码
　　-charset UTF-8      //-charset charsetName 用于跨平台查看文档的字符集，它对应着你生成的html
　　　　　　　　　　　文件中的头部的charset
Finish,然后就可以看到生成的文档了，很高效的工具。
如果想了解更多的javadoc的选项：进入命令行，输入：javadoc -help ，如果你的环境变量配置的正确的话，你可以看到全部的选项