java学习（1）--注释文档和编码规范

java有两种注释风格，一种是传统的C语言风格的注释——C++也继承了这一种风格。这种注释以/*开头 以*/结束。相必都很熟悉了，就不多说。另一种是单行注释 也就是以“//”开头直到句末。

关于注释文档

为了使文档和代码的连接性更强，最好的方法是把代码和文档联结起来，最简单的办法就是把所有东西都放到一个文件里。这就需要用到了一种特殊的注释语法来标记文档；此外还需要一个工具来提取这些注释，并将它们转换成有用的形式，这个工具就是javadoc，他是jdk安装的一部分。javadoc输出的是一个HTML文件，可以用浏览器进行查看，如果要对javadoc处理过的信息执行特殊的操作，暗恶魔可以编写自己的被称为“doclets”的javadoc处理器来实现。（doclets参见http://MindView.net/Books/Better Java所提供的补充材料）

语法

所有javadoc命令都在“/**”注释中出现，注释部分结束还是“*/”。javadoc使用的方式主要有两种：嵌入式HTML，或者使用“文档标签”。独立文档标签是一些以“@”字符开头的命令，并且要放在注释行的最前面（不算前导“*”）。行内文档标签可以出现在javadoc注释中的任何地方，也是以“@”开头，但是要括在花括号里面。
三种类型的注释文档，对应注释位置后面的三种元素：类，域和方法。

/**A class comment*/
public class Document {
    /**A filed comment*/
    public int a;
    /**A method comment*/
    public void f(){
        
    }
}///:~

注意：javadoc只对公共和保护成员进行文档注释有效，不过可以使用-private进行标记。
生成方法：

//javadoc -d ***（输出的文件夹名字） **.java（文件来源）
//example
java -d mydoc Document.java

嵌入式HTML

可以嵌入一些html格式 但是不要使用标题标签 因为可能会和javadoc插入的自己的标签冲突。

标签示例

1.@see：引用其他类
允许客户引用其他类的文档，在生成的HTML文件当中，会通过@see标签连接到其他文件（插入超链接See Also）
2.{@link package.class#member label}
用法和see相似，但是这个用于行内，同时用label作为超链接文本而不是see also
3.{@docRoot}
该文档产生到文档根目录的相对路径，用于文档树页面的显式超链接
4.{@inheritDoc}
该标签从当前这个类的最直接的基类中继承相关文档到当前的文档注释中
5.@version
使用格式：@version version-information
6.@author
@author author-information
7.@since
该标签允许指定程序代码最早使用的版本
8.@param
用于方法文档：@param parameter-name description
parameter-name 参数名
description：可延续数行的文本终止于新的文档标签出现之前
9.@return
@return description
描述返回值的含义 可数行
10.@throws
@throws fully-qualified-class-name description / /抛出 异常类名称 类的描述
11.@deprecated
这个标签用来指出一些旧特性已经由改进的新特性所取代，建议用户不要使用这些旧特性，因为在不久的将来他们很可能会被删除。若使用了一个被标为@deprecated的方法会引起编译器发出警告。
在javaSE5中，@deprecated已经被@Deprecated替代。

JAVA编码风格

类的首字母大写；如果类名由几个单词构成，那么把他们并在一起，其中每个单词首字母大写。（驼峰风格）