参考文章,百度百科
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) | 静态值域 |
在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 api@package.txt
注:api表示帮助文档的存放目录名,@package.txt表示以文件的形式传入包名。
附录1:javadoc命令语法。
在命令行输入javadoc回车就会出现如下的帮助信息:
javadoc用法:javadoc [选项] [软件包名称] [源文件] [@file]
-overview<文件>
-public
-protected
-package
-private
-help
-doclet<类>
-docletpath<路径>
-sourcepath<路径列表>
-classpath<路径列表>
-exclude<软件包列表>
-subpackages <子软件包列表>指定要递归装入的子软件包
-breakiterator
-bootclasspath <路径列表>覆盖引导类加载器所装入的类文件的位置
-source<版本>
-extdirs<目录列表>
-verbose
-locale<名称>
-encoding<名称>
-quiet
-J<标志>
通过标准 doclet 提供:
-d<directory>
-use
-version
-author
-docfilessubdirs
-splitindex
-windowtitle<text>
-doctitle<html-code>
-header<html-code>
-footer<html-code>
-top
-bottom<html-code>
-link<url>
-linkoffline <url><url2>
-excludedocfilessubdir<name1>:..排除具有给定名称的所有文档文件子目录。
-group <name><p1>:<p2>..在概述页面中,将指定的包分组
-nocomment
-nodeprecated
-noqualifier<name1>:<name2>:...输出中不包括指定限定符的列表。
-nosince
-notimestamp
-nodeprecatedlist
-notree
-noindex
-nohelp
-nonavbar
-serialwarn
-tag<name>:<locations>:<header>指定单个参数自定义标记
-taglet
-tagletpath
-charset<charset>
-helpfile<file>
-linksource
-sourcetab <tablength>
-keywords
-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开源项目,只要有源码就可以。