JavaDoc简记

我们在开发JAVA程序中, 可以使用Javadoc来进行程序文档的整理, 当程序编写完成, 利用Java自带的JavaDoc工具就可以生成规范的API说明手册.而且在编辑器内可以看到类或者方法的说明，这对于代码的重用有很高的意义！！
javadoc 的语法是在代码文件内部使用的
javadoc 命令是在CMD状态下的一个指令生成代码文件的说明文件（html）
注释说明的几个建议和原则
1.类如何相互关联
2.方法如何影响对象的状态
3.方法如何将出错条件通知它们的调用者以及它们可能通知什么错误
4.类如何处理多线程应用程序中的使用
5.方法的参数作用域及其返回值的范围

另外，糟糕的文档（或甚至更糟糕，没有文档）会导致优秀的代码不可用或不可重用。通过在文档上花一些额外时间，您将为您的用户（可能是您自己）避免无数的挫折。

书写格式:
/** <- 这里一定要用两个星号, 否则会被认为是普通注释的
* ……..
*/
（java有三种注释格式// /* /**， 其中/**是专门设计来给javadoc用的）

public int getCount() { …….
Javadoc只能为public,protected两种权限的类成员进行处理注释文档。当然也可以使用-private参数强制进行处理, 我们可以在注释中嵌入HTML个标记来丰富最后文档的显示, 因为Javadoc最后生成的文档就是HTML.

/**
* 一些参数列表<p>
*
* @see 类名
* @see 完整类名
* @see 完整类名#方法
*
* @param 参数名 说明
* @return 说明
* @exception 完整类名 说明
* @deprecated
*
* @version 版本信息
* @author 作者名
*/
说明:
@see : 就是文档中的 参见xx 的条目, 其实就是超链接.

一般来说, 文档有三种类型: 类注释, 变量注释, 方法注释, 这三中类型的注释除了都可以包含 @see 参数外, 其它所包含的参数是不同的.
1. 类注释
类注释是写在类前面的, 用来说明类的一些情况, 可以包涵 @version,@author参数, 但Javadoc缺省情况下不处理, 也就是说不在最后文档中出现的, 为了使用这些信息, 我们可以加入参数 -version和 -author来强制输出到最后的文档中.
2. 变量注释
变量注释写在变量前面, 只能包含 @see 参数
3. 方法注释
方法注释可以包括
@param : 参数名是指参数列表内的标识符, 说明就是一些解释性质的文字, 可以多行.
@return : 返回值的说明, 可以多行
@exception : 完整类名应该明确指定一个违例类的名字，它是在其它某个地方定义好的。而说明则阐述为什么这种特殊类型的违例会在方法调用中出现。说明可以多行
@deprecated : 指出一些旧功能已由改进过的新功能取代。该标记的作用是建议用户不必再使用一种特定的功能，因为未来改版时可能摒弃这一功能。若将一个方法标记为@deprecated，则使用该方法时会收到编译器的警告。


生成javadoc可能会遇到的问题：
1、在生成javadoc的时候，如果遇到“编码GBK不可映射字符”，
那么
Generate javadoc–>next–>next–> 在 “Extra javadoc options”下面的文本框中填入 ” -encoding UTF-8 -charset UTF-8 “.（这个操作用的是eclipse的导出javadoc）