Java-Notes Documents

 1.注释：编译时, /*和*/之间的所有东西都会被忽略. 在连续注释内容的每一行都以一个*开头.

2.注释文档：将代码和文档放到同一个文件中有利于二者的统一管理, 这就需要特殊的注释语法和一个提取注释的工具.

提取注释的工具：javadoc, 查找程序中的特殊注释标签, 解析由这些标签标记的信息, 同时将毗邻注释的类名or方法名提取出来.
javadoc输出的是一个html文件. 有个javadoc, 就有了创建文档的标准.

注释语法：javadoc只能在/**和*/注释中出现. 使用javadoc的方式有两种(1)嵌入html (2)使用"文档标签".
独立文档标签：以"@"字符开头的命令, 且要置于注释行的最前面.
行内文档标签：以"@"字符开头的命令, 可以出现在javadoc注释中的任何地方, 但要括在花括号内.
共有三种类型的注释文档, 分别对应于注释位置后面的三种元素: 类, 变量, 方法. 即: 类注释正好位于类定义之前; 变量注释正好位于变量定义之前; 方法注释正好位于方法定义之前.

javadoc只能为public和protect成员进行文档注释, private和包内可访问成员的注释会被忽略. 因为只有public和protect成员才能在文件之外被使用. 至于所有对类所作的注释, 则都会包含在输出结果中.

嵌入式html：主要目的是为了对代码及注释进行格式化.
在文档注释中, 位于每一行开头的星号和前导空格都会被javadoc丢弃. javadoc会对所有内容重新格式化, 使其与标准的文档外观一致. 不要在嵌入式html中使用标题标签, 例如<hl><hr>, 因为javadoc会插入自己的标题, 而你的标题可能同它们发生冲突.

javadoc标签示例
@version标签
格式：@version version-information
如果javadoc命令行使用了"-version"标记, 那么就从生成的html文档中提取出版本信息(即version-information).

@author标签
格式：@author author-information
如果javadoc命令行使用了"-author"标记, 那么就从生成的html文档中提取出作者信息(即author-information).
可以使用多个标签, 以便列出所有作者, 但是它们必须连续放置. 全部作者信息会合并到同一段落, 置于生成的html中.

@param标签
格式：@param parameter-name description 该标签用于方法文档中.

@return标签
格式：@return description 该标签用于方法文档中.

@throws标签
格式：@throws fully-qualified-class-name description
fully-qualified-class-name给出一个异常类的无歧义的名字. description告诉你为什么此异常类会在方法调用中出现.

//: c02:HelloDate.java
import java.util.*;

/** *//**
 * Title: HelloDate类<br>
 * Description: 通过HelloDate类来说明java文档注释<br>
 * Description: Display a String and today's date<br>
 * Copyright: (c) 2008 Forest He<br>
 * Company: 群硕<br>
 * @author Bruce Eckel
 * @author www.BruceEckel.com
 * @version 2.0
 */
public class HelloDate...{
    /** *//**
     * Sole entry point to class & application
     * @param args array of String arguments
     * @return No return value
     * @exception No exceptions thrown
     */
    public static void main(String[] args) ...{
        System.out.println("Hello, it's: ");
        System.out.println(new Date());
    }
}///:~

第一行采用自己独特的方法, 用一个":"作为特殊记号说明这是包含源文件名的注释行. 该行包含文件的路径信息(c02代表第2章), 随后是文件名. 最后一行的注释"///:~"标志源代码清单的结束.

编码风格：类名的首字母要大写; 如果类名由几个单词构成, 那么把它们并在一起(即不要用下划线来分隔名字), 其中每个内部单词的首字母都采用大写形式.
这种风格称为"驼峰风格". 其他所有内容(方法, 成员变量, 对象引用名称等), 公认的风格与类的风格一样, 只是标识符的第一个字母要小写.