JAVA ---掌握Java程序的注释用法

 （一）掌握Java程序的注释用法

        程序注释用来对程序中的代码进行说明。注释的内容在程序运行时会被编译器忽略，因而不参与程序的运行。
       Java有三种程序注释方式，分别为单行注释、多行注释和文档注释，其特点如下：

①单行注释以双斜杠“//”开始，终止于本行结束。单行注释多用于对一行代码的简短说明。

②多行注释以“/”开始，以“*/”结束，两者之间的所有字符都是多行注释的内容。多行注释通常用于对文件、方法、数据结构等的说明，或者算法的描述。多行注释一般位于方法的前面，起引导作用，也可以根据需要放在其他合适的位置。

③文档注释以“/**”开始，以“*/”结束，在此之间的所有字符都是文档注释的内容。文档注释主要是为了支持JDK工具javadoc，通过javadoc，文档注释将会生成HTML格式的代码报告，因此文档注释应当书写在类、构造方法、成员方法以及常量或变量的定义之前。
 相关代码：

package com.sxt;

import java.io.*;

/**
 * 这个类演示了3.文档注释
 * @author Ayan Amhed
 * @version 1.2
 */
public class SquareNum {
    /**
     * 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.
     * @return Nothing.
     * @exception IOException On input error.
     * @see IOException
     */
    //1.单行注释（在这一行后面无论写啥都参与编译器运行）
    /*（在这一区域无论写啥都参与编译器运行）
    2.多行注释;
    hhhh；
    哈哈哈;
     
     */
    public static void main(String args[]) throws IOException
    {
        SquareNum ob = new SquareNum();
        double val;
        System.out.println("Enter value to be squared: ");
        val = ob.getNumber();
        val = ob.square(val);
        System.out.println("Squared value is " + val);
    }
}

（二）常见的几个注释

• @author 标明开发该类模块的作者，多个作者之间使用,分割

• @version 标明该类模块的版本

• @see 参考转向，也就是相关主题

• @since 从哪个版本开始增加的

• @param 对方法中某参数的说明，如果没有参数就不能写（后面再学）

• @return 对方法返回值的说明，如果方法的返回值类型是void就不能写（后面再学）

• @throws/@exception 对方法可能抛出的异常进行说明 ，如果方法没有用throws显式抛出的异常就不能写（后面再学）

其中 @param @return 和 @exception 这三个标记都是只用于方法的。

• @param的格式要求：@param 形参名 形参类型 形参说明

• @return 的格式要求：@return 返回值类型 返回值说明

• @exception 的格式要求：@exception 异常类型 异常说明

• @param和@exception可以并列多个

使用javadoc工具可以基于文档注释生成API文档。

用法: javadoc [options] [packagenames] [sourcefiles] [@files]