javaDoc和java文件的注释以及javadoc生成出现的问题【dos option选项】

参考文章，百度百科

                    http://88250.b3log.org/when-the-little-things-count-javadoc

                    javadoc的查看帮助文档：http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#serial（可惜是英文的）

                   http://my.oschina.net/u/1415486/blog/339343

                   http://my.oschina.net/u/1415486/blog/339289

                   http://blog.chinaunix.net/uid-725717-id-2060139.html

                   http://my.oschina.net/tiancai/blog/155299

                   http://blog.sina.com.cn/s/blog_6d5c82a70100omah.html  javadoc命令和器options【选项】

Java中有三种注释方式：

①单行注释，符号://注释内容

②段落注释，即多行注释，符号:/*注释内容*/

③文档注释，用于生成HTML格式的API（Application Program Interface,应用程序接口）注释文档，符号:/**注释内容*/

文档注释根据它所注释的内容，分为3类：变量，方法和类。也就是说，类的注释一定要出现在类定义的前面；变量注释要出现在变量定义的前面；而方法注释则要出现在方法定义的前面。注释和定义之间不能有任何东西。

javadoc，顾名思义即java文件的文档，也就是我们常见的文档，打开javadoc文件的话如下图

dos生成命令：F:\java>-d 文件保存目录 javadoc javadoc.java,格式为：文件所在目录：javadoc用法：javadoc [选项] [软件包名称] [源文件] [@file]

注：文件所在目录必须填写完整，此处会保存在指定的文件夹中，当然javadoc还有很多命令。

eclipse下生成：File->Export->java->javadoc 然后一步一步的来。

注：javadoc command框中填写 C:\Program Files\Java\jdk1.6.0_43\bin\javadoc.exe 本人的jdk安装在c盘啦。

dos下生成javadoc的常用命令：请看这篇文章http://blog.chinaunix.net/uid-725717-id-2060139.html

生成过程中可能出现的错误：”编码 GBK 的不可映射字符“，这是因为中文注释的问题。http://my.oschina.net/tiancai/blog/155299

eclipseFile->Export->java->javadoc，选中项目后不要直接finish，一直next 最后一步VM中添加如下代码-encoding utf-8 -charset utf-8

dos下如何处理，请搜javadoc命令即可，解决方法如下:

F:\java>-d 文件保存目录 -encoding UTF-8 -charset UTF-8 javadoc javadoc.java

java文件中常用的几个标记，标记后面还可以添加html 的标签<h3>html字号标签</h3><a href="www.kengni.com">加入的html的超链接</a>

标签	说明	JDK 1.1 doclet	标准doclet	标签类型
@author 作者	作者标识	√	√	包、 类、接口
@version 版本号	版本号	√	√	包、 类、接口
@param 参数名 描述	方法的入参名及描述信息，如入参有特别要求，可在此注释。	√	√	构造函数、 方法
@return 描述	对函数返回值的注释	√	√	方法
@deprecated 过期文本	标识随着程序版本的提升，当前API已经过期，仅为了保证兼容性依然存在，以此告之开发者不应再用这个API。	√	√	包、类、接口、值域、构造函数、 方法
@throws异常类名	构造函数或方法所会抛出的异常。		√	构造函数、 方法
@exception 异常类名	同@throws。	√	√	构造函数、 方法
@see 引用	查看相关内容，如类、方法、变量等。	√	√	包、类、接口、值域、构造函数、 方法
@since 描述文本	API在什么程序的什么版本后开发支持。	√	√	包、类、接口、值域、构造函数、 方法
{@link包.类#成员 标签}	链接到某个特定的成员对应的文档中。		√	包、类、接口、值域、构造函数、 方法
{@value}	当对常量进行注释时，如果想将其值包含在文档中，则通过该标签来引用常量的值。		√(JDK1.4)	静态值域

此外还有@serial、@serialField、@serialData、{@docRoot}、{@inheritDoc}、{@literal}、{@code} {@value arg}几个不常用的标签，由于不常使用，我们展开叙述，感兴趣的读者可以查看帮助文档。

在java文件中如何使用javadoc，请看如下代码实例，当然此处仅供参考，主要是列出常见的，其实这是极不规范。

package com.yue.test;

import java.io.IOException;

public class JavaDocTest {

	/**
	 * 
	 * @Title: main 
	 * @param args 
	 * void 
	 * @author shimy
	 * @since 2016-5-3 V 1.0
	 */
	public static void main(String[] args) {
		try {
			new JavaDocTest().javaDocTest("javadoc");
		} catch (IOException e) {
			e.printStackTrace();
		}
	}
	
	/**
	 * 
	 * @ClassName: MyTestInClass 
	 * @Description: TODO 
	 * @author shimy
	 * @date 2016-5-3 上午8:49:11 
	 *
	 */
	private class MyTestInClass{
		/**
		 * 
		 * @Title: inTest  
		 * void 
		 * @author shimy
		 * @since 2016-5-3 V 1.0
		 */
		private void inTest(){
			try {
				new JavaDocTest().javaDocTest("javadoc");
			} catch (IOException e) {
				// TODO Auto-generated catch block
				e.printStackTrace();
			}
		}
	}
	/**
	 * @author <h5>Administrator(作者)</h5>
	 * @version v1.1 (版本号)
	 * @Title: javaDocTest(方法名)
	 * @param javaDocName(参数名 描述)
         * @return  String(对函数返回值的注释)
	 * @deprecated 过期文本，不建议使用，将来可以摒弃，加入此标记后可以看到我们的javaDocTest方法划上了横杠
	 * @throws @throws IOException(异常类名)
	 * @exception IOException 异常类名
	 * {@hide} (注明此方法为隐藏方法，其他对象调用不出来，仅供此类和此类的内部类调用,看上面)
	 * @see MyTestInClass#inTest() #inTest() 引用,引用的别的类的方法或参数
	 * @since 2016-5-3 V 1.0(描述文本,API在什么程序在什么版本后开发支持)
	 * {@link com.yue.test.JavaDocTest#javaDocTest(String)}[链接到某个特定的成员对应的文档中(填写格式：包.类#成员 标签),此处链接到自己的方法]
	 * {@value 类型String}(对函数返回值的注释)
	 * 下面几个不常用
	 * @serial 可序列化(可串行化)文件命令
	 * @serialField 
	 * @serialData
	 * {@docRoot}
	 * {@inheritDoc}
	 * {@literal}
	 * {@code} 
	 * 
	 */
	private String javaDocTest(String javaDocName) throws IOException{
		new MyTestInClass().inTest();
		return javaDocName;
	}
}

经过上面的代码，我发现并没有生成自己想要的javadoc，我的自定方法和参数没有在javadoc下出现，这也正是需要注意的地方 。
请看下图红色标注，大家制定权限就可以啦，至于dos命令F:\java>-d 文件保存目录 -public  javadoc javadoc.java(蓝色标注为权限)，点击打开链接，此处不做陈述。

做一下记录，来自http://blog.sina.com.cn/s/blog_6d5c82a70100omah.html，大家也可以看javadoc帮助文档

打开命令行窗口，输入命令生成api文档。
转到目录：D:\Downloads\swt-3.5.2-win32-win32-x86\src，输入如下命令生成文档。
javadoc -d [email protected]
注：api表示帮助文档的存放目录名，@package.txt表示以文件的形式传入包名。

附录1：javadoc命令语法。
在命令行输入javadoc回车就会出现如下的帮助信息：

javadoc用法：javadoc [选项] [软件包名称] [源文件] [@file]
-overview<文件>         读取 HTML 文件的概述文档
-public                  仅显示公共类和成员 //带有public修饰符
-protected               显示受保护/公共类和成员（默认） //带有protected、public修饰符
-package                 显示软件包/受保护/公共类和成员 //不带修饰符，或带有protected、public修饰符
-private                 显示所有类和成员 //不带修饰符，或带有任何修饰符
-help                    显示命令行选项并退出
-doclet<类>             通过替代 doclet 生成输出
-docletpath<路径>       指定查找 doclet 类文件的位置
-sourcepath<路径列表>   指定查找源文件的位置
-classpath<路径列表>    指定查找用户类文件的位置
-exclude<软件包列表>    指定要排除的软件包的列表
-subpackages <子软件包列表>指定要递归装入的子软件包
-breakiterator           使用 BreakIterator 计算第 1 句
-bootclasspath <路径列表>覆盖引导类加载器所装入的类文件的位置
-source<版本>           提供与指定版本的源兼容性
-extdirs<目录列表>      覆盖安装的扩展目录的位置
-verbose                 输出有关 Javadoc 正在执行的操作的消息
-locale<名称>           要使用的语言环境，例如 en_US 或 en_US_WIN
-encoding<名称>         源文件编码名称
-quiet                   不显示状态消息
-J<标志>                 直接将 <标志> 传递给运行时系统

通过标准 doclet 提供:
-d<directory>                   输出文件的目标目录
-use                             创建类和包用法页面
-version                         包含 @version 段
-author                          包含 @author 段
-docfilessubdirs                 递归复制文档文件子目录
-splitindex                      将索引分为每个字母对应一个文件
-windowtitle<text>              文档的浏览器窗口标题
-doctitle<html-code>            包含概述页面的标题
-header<html-code>              包含每个页面的页眉文本
-footer<html-code>              包含每个页面的页脚文本
-top   <html-code>              包含每个页面的顶部文本
-bottom<html-code>              包含每个页面的底部文本
-link<url>                      创建指向位于 <url> 的 javadoc 输出的链接
-linkoffline <url><url2>        利用位于 <url2> 的包列表链接至位于<url> 的文档
-excludedocfilessubdir<name1>:..排除具有给定名称的所有文档文件子目录。
-group <name><p1>:<p2>..在概述页面中，将指定的包分组
-nocomment                       不生成描述和标记，只生成声明。
-nodeprecated                    不包含 @deprecated 信息
-noqualifier<name1>:<name2>:...输出中不包括指定限定符的列表。
-nosince                         不包含 @since 信息
-notimestamp                     不包含隐藏时间戳
-nodeprecatedlist                不生成已过时的列表
-notree                          不生成类分层结构
-noindex                         不生成索引
-nohelp                          不生成帮助链接
-nonavbar                        不生成导航栏
-serialwarn                      生成有关 @serial 标记的警告
-tag<name>:<locations>:<header>指定单个参数自定义标记
-taglet                          要注册的 Taglet 的全限定名称
-tagletpath                      Taglet 的路径
-charset<charset>               用于跨平台查看生成的文档的字符集。
-helpfile<file>                 包含帮助链接所链接到的文件
-linksource                      以 HTML 格式生成源文件
-sourcetab <tablength>          指定源中每个制表符占据的空格数
-keywords                        使包、类和成员信息附带 HTML 元标记
-stylesheetfile<path>           用于更改生成文档的样式的文件
-docencoding<name>              输出编码名称

附录2：常用命令举例。
javadoc -d apiorg/eclipse/swt/SWT.java //处理单个源文件
javadoc -dapi org.eclipse.swt //处理单个包
javadoc -d apiorg.eclipse.swt org.eclipse.swt.widgets //处理多个包，如果处理的包较少，可以采用直接输入的方法
javadoc -private -d api @package.txt //处理多个包。生成最完整的帮助文档，包括带有private修饰符的属性和方法。

注：本文制作api的方法，适用于所有java开源项目，只要有源码就可以。