Java| Javadoc生成Java帮助文档

时间：2021-02-10 09:34:53

一.JavaDoc介绍

Javadoc是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档。

比如官网JDK1.7API

二.注释的种类

    /** * 注释种类3 * * @param args */
    public static void main(String[] args) {

        // 注释种类1

        /* 注释种类2 */

    }

注释的功能解释:

// 第1种注释，双斜线，不支持换行

/* 第2种注释，支持换行，这里面的都是注释 */

/** * 第3种注释，在斜线后，有两个星号，这样的注释，便是Javadoc文档注释 */
/** Javadoc文档注释也可以不换行 */

本文中主要是讲解第三种,也就是文档注释.

三.Tag功能介绍

tag 描述 例子
@author 用于class和interface的声明中，表示作者 @author 作者名
@param 用于构造函数及函数的参数说明 @param 参数名 参数说明
@return 表示函数的返回值 @return 函数返回值说明
@throws 标识出方法可能抛出的异常 @throws RuntimeException 描述
@exception 和@throws一样，官网推荐用@throws
@see 链接目标，@see Tag只能顶格写 @see 其他类
{@link} 和@see类似，但可以放在任意位置 {@link 其他类名}
@since 引入新功能 @since 2.0，2.0版本开始加入的新功能
@version 指定类的版本 @version info
@deprecated 类或成员deprecated
{@value} 显示常量的值，该常量必须是final属性
{@code }
{@docRoot} 文档的根路径

@author

默认Javadoc是不显示@author Tag的内容的。

如果打算在Javadoc里显示@author的内容，可以在生成Javadoc的时候，添加参数 -tag author:a:”Author:”

@return

当Tag @return用在返回值为void的函数上或者构造函数，@return会被忽略

@see

@see “string”

如果在@see后面添加一段文本字符串，则不会生成连接。Javadoc 工具会根据文本前的双引号来进行识别
例如：
@see “The Java Programming Language”
生成的结果就是

See Also:
     "The Java Programming Language"

@see label

跳转到相应连接

@see package.class#member label

跳转到相应class的成员或class

@see 的查找

如果在class内，可以不加包和类的限定名

/** * @see #field * @see #method(Type, Type,...) */

在当前package或引用的package内查找

/** * @see Class#field * @see Class#method(Type, Type,...) */

在其他package内查找

/** * @see package.Class#field * @see package.Class#method(Type, Type,...) * @see package.Class */

@see Tag内的名称，的查找次序为：

1. 当前class或interface
2. enclosing classes
3. 父类或父接口
4. 当前包
5. 按import次序，查找import的包，class和interface

{@value}

{@value} 在生成的doc里，会用变量的真实值替换{@value}出现的地方。有两种用法：

一种是没有参数，只能用在final修饰的成员变量上

/** * The value of this constant is {@value}. */
public static final String SCRIPT_START = "<script>"

使用参数，{@value package.class#field}。在生成的Javadoc内，会显示参数的值.

  /** * * if equal {@value #TEST_STATIC} */
  public boolean isTestString(String str){
  }

{@code}

在这个Tag里，可以直接显示很多html里需要转义的字符，比如 <> &，同时，文本的字体也会以code的字体显示

四.生成Java帮助文档

代码例子:

/** * TestJavaDoc类说明 * * @author Yves He * */
public class TestJavaDoc {
    /** * 方法的简述: 测试testJavaDoc * <p> * 方法详细说明第一行:测试JavaDoc详细说明1<br> * 方法详细说明第二行:测试JavaDoc详细说明2<br> * * @param message * 方法参数说明 * @return 返回值说明 * @throws Exception * 异常说明 */
    public static String testJavaDoc(String message) throws Exception {
        return "hello " + message;
    }

}

  • 1.命令行方式生成Java帮助文档
    javadoc -public -sourcepath D:\workspace\eclipse\javadoc\src -subpackages cn.com.yves -encoding utf-8 -charset utf-8 -d D:\javadocout

    用法: javadoc [options] [packagenames] [sourcefiles] [@files]
  -overview <file> 从 HTML 文件读取概览文档   -public 仅显示 public 类和成员   -protected 显示 protected/public 类和成员 (默认值)   -package 显示 package/protected/public 类和成员   -private 显示所有类和成员   -help 显示命令行选项并退出   -doclet <class> 通过替代 doclet 生成输出   -docletpath <path> 指定查找 doclet 类文件的位置   -sourcepath <pathlist> 指定查找源文件的位置   -classpath <pathlist> 指定查找用户类文件的位置   -cp <pathlist> 指定查找用户类文件的位置   -exclude <pkglist> 指定要排除的程序包列表   -subpackages <subpkglist> 指定要递归加载的子程序包   -breakiterator 计算带有 BreakIterator 的第一个语句   -bootclasspath <pathlist> 覆盖由引导类加载器所加载的                                    类文件的位置
  -source <release> 提供与指定发行版的源兼容性   -extdirs <dirlist> 覆盖所安装扩展的位置   -verbose 输出有关 Javadoc 正在执行的操作的信息   -locale <name> 要使用的区域设置, 例如 en_US 或 en_US_WIN   -encoding <name> 源文件编码名称   -quiet 不显示状态消息   -J<flag> 直接将 <flag> 传递到运行时系统   -X 输出非标准选项的提要 
通过标准 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 <tab length> 指定源中每个制表符占据的空格数   -keywords 使程序包, 类和成员信息附带 HTML 元标记   -stylesheetfile <path> 用于更改生成文档的样式的文件   -docencoding <name> 指定输出的字符编码

  • 2.Eclipse中生成Java帮助文档
    选中项目–>export–>javadoc
    1)选择项目那些权限的内容输出到帮助文档.
    Java| Javadoc生成Java帮助文档
    2) 选择需要提取的注解.
    Java| Javadoc生成Java帮助文档
    3)根据项目的编码设置指定的编码和字符集.
    UTF8项目的设置: -encoding utf-8 -charset utf-8
    Java| Javadoc生成Java帮助文档

JavaDoc帮助文档效果:
Java| Javadoc生成Java帮助文档

参考链接:
http://blog.csdn.net/shuanghujushi/article/details/73433648
http://blog.csdn.net/skylake_/article/details/65631591
http://blog.chinaunix.net/uid-725717-id-2060139.html

官网:
https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#encoding
http://www.oracle.com/technetwork/articles/java/index-137868.html

标签：

相关文章