java 生成doc 加入图片 java怎么生成doc

转载

mob64ca1407216b 2024-07-02 09:19:45

文章标签 java 生成doc 加入图片 api javadoc java 注释 文章分类 Java 后端开发

写这篇文章完全是一时兴起，因为在此之前，我其实也并没有使用过 Java Doc 的功能。但是即使很少使用得到，但是你不得不承认，如果公司的API能够整理出这么一套API，我想每一个刚入职的员工都会对它爱不释手的。

代码中注释的使用

1. 首先看一个Demo：

import java.util.*;


/**
 * @author WithWings
 * @version 1.1
 * @since 1.8
 */
public class HelloWorld{

    public static String hello = "Hello,World!";

    public static void main(String[] args){
        try{
        sayHello(hello);
        }catch(Exception e){
            e.printStackTrace();
        }
    }


    /**
     * 主项目工程执行方法，运行 .class 文件后自动执行 mian方法
     * @param s 参数
     * @return 返回的参数
     * @see Image
     * @see #hello
     * @exception Exception 提供异常处理 方法一
     * @throws Exception 提供异常处理 方法二
     */
    public static String sayHello(String s) throws Exception{
        System.out.println(s);
        System.out.println(new Date());
        try{
            Thread.currentThread().sleep(5 * 1000);
        }catch( InterruptedException e){
            e.printStackTrace();
        }

    return s;
    }

    public class Image{

        /**
         * @deprecated 标记该API过时 
         */
        public void printImage(){
            System.out.println("Image");
        }
    }
}

@author 作者（只出现在类和接口的文档中）
@version 数字指的是版本号
@since 数字指的jdk版本
@param 指的是方法的参数，后面跟上参数名 + 空格 + 参数说明
@return 对返回值的说明
@see 添加引用的类或者参数

@see 类名
@see #方法名或参数名
@see 类名#参数名

@throws 抛出异常说明，后面跟上异常名 + 空格 + 异常跑出原因

2. 上面是我自己用到的，然而这些并不是很齐全，但是很幸运，我在极客学院找到一个表格，图省事我就直接copy过来了。

标签	描述	语法
@author	添加类的作者	@author name-text
{@code}	不把文本转换成 HTML 标记和嵌套的 Java 标签而用代码字体展示它	{@code text}
{@docRoot}	表示从任何生成页面到生成文档的根目录的相对路径	{@docRoot}
@deprecated	添加一个注释暗示 API 应该不再被使用	@deprecated deprecated-text
@exception	用类名和描述文本给生成的文档添加一个副标题	@exception class-name description
{@inheritDoc}	从最近的可继承的类或可实现的接口继承注释	Inherits a comment from the immediate surperclass.
{@link}	用指向特定的包，类或者一个引用类的成员名的文档的可见文本标签插入在线链接	{@link package.class#member label}
{@linkplain}	和{@link}相同，除了链接的标签用纯文本标示而不是代码字体	{@linkplain package.class#member label}
@param	给“参数”区域添加一个有特定参数名且后跟着特定描述的参数	@param parameter-name description
@return	添加一个有描述文本的“Returns”区域	@return description
@see	添加带有链接或者指向引用的文本入口的标题“See Also”	@see reference
@serial	在默认的序列化字段的文本注释中使用	@serial field-description	include	exclude
@serialData	记录由 writeObject( ) 或 writeExternal( )方法所写的数据	@serialData data-description
@serialField	记录一个 ObjectStreamField 成分	@serialField field-name field-type field-description
@since	给生成的文档添加一个带有特定 since 文本的”Since”标题	@since release
@throws	@throw 和 @exception 标签是同义词	@throws class-name description
{@value}	当{@value}被用在一个静态字段的文本注释中，它展示了那个常量的值	{@value package.class#field}
@version	当 -version 选项被使用时用特定的 version w文本给生成的文本添加一个“Version”副标题	@version version-text

3. 接下来就是最后一步，生成了，说实话，我之前不使用Java Doc 的原因，很大一部分就是因为，生成命令过于复杂了。但是这次，我做了一个仔细的分析，力求可以清晰的使用，并且总结两条常用的可以让大家直接复制生成doc的常用命令。

单个Java文件：

javadoc -locale zh_CN -d [apidoc] -windowtitle [title] -doctitle [doctitle] -encoding UTF-8 -charset UTF-8  *HelloWorld.java

[apidoc] : 替换成希望生成的doc文档名
[title] : 替换成网页标题
[doctitle] : 替换成文档题目
[*HelloWorld.java] : 替换成要编译的文件

多文件多包：

包的根目录处新建 packagepath.txt 文件：

    内容为每个类所在的包名，这个不适用通配符，不会自动读取子目录，所以要把所有用到的全部列出来，中间使用空格隔开，没有办法读取根目录处的java文件。

javadoc -locale zh_CN -d [apidoc] -windowtitle [title] -doctitle [doctitle] -encoding UTF-8 -charset UTF-8 @packagepath.txt

或者直接：

javadoc -locale zh_CN -author -version -d [apidoc] -windowtitle [title] -doctitle [doctitle] -encoding UTF-8 -charset UTF-8  @packagepath.txt

[apidoc] : 替换成希望生成的doc文档名
[title] : 替换成网页标题
[doctitle] : 替换成文档题目
[*HelloWorld.java] : 替换成要编译的文件

想要包含版本号和作者的话，在 -locale zh_CN 后添加 -author -version

javadoc -locale zh_CN -author -version -d [apidoc] -windowtitle [title] -doctitle [doctitle] -encoding UTF-8 -charset UTF-8  包名1 包名2 包名3

4. 详细的命令使用，有心研究的可以看一下

javadoc -help
用法：javadoc [选项] [软件包名称] [源文件] [@file]
-overview <文件>          读取 HTML 文件的概述文档
-public                   仅显示公共类和成员
-protected                显示受保护/公共类和成员（默认）
-package                  显示软件包/受保护/公共类和成员
-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 <目录>                         输出文件的目标目录
-use                              创建类和软件包用法页面
-version                          包含 @version 段
-author                           包含 @author 段
-docfilessubdirs                  递归复制文档文件子目录
-splitindex                       将索引分为每个字母对应一个文件
-windowtitle <文本>               文档的浏览器窗口标题
-doctitle <html 代码>             包含概述页面的标题
-header <html 代码>               包含每个页面的页眉文本
-footer <html 代码>               包含每个页面的页脚文本
-bottom <html 代码>               包含每个页面的底部文本
-link <url>                       创建指向位于 <url> 的 javadoc 输出的链接
-linkoffline <url> <url2>         利用位于 <url2> 的软件包列表链接至位于 <url>
的文档
-excludedocfilessubdir <名称 1>:..排除带有给定名称的所有文档文件子目录。
-group <名称> <p1>:<p2>..         在概述页面中，将指定的软件包分组
-nocomment                        抑止描述和标记，只生成声明。
-nodeprecated                     不包含 @deprecated 信息
-noqualifier <名称 1>:<名称 2>:...从输出中排除限定符的列表。
-nosince                          不包含 @since 信息
-notimestamp                      不包含隐藏时间戳
-nodeprecatedlist                 不生成已过时的列表
-notree                           不生成类分层结构
-noindex                          不生成索引
-nohelp                           不生成帮助链接
-nonavbar                         不生成导航栏
-serialwarn                       生成有关 @serial 标记的警告
-tag <名称>:<位置>:<标题>         指定单个变量自定义标记
-taglet                           要注册的 Taglet 的全限定名称
-tagletpath                       Taglet 的路径
-charset <字符集>                 用于跨平台查看生成的文档的字符集。
-helpfile <文件>                  包含帮助链接所链接到的文件
-linksource                       以 HTML 格式生成源
-sourcetab <制表符长度>           指定源中每个制表符占据的空格数
-keywords                         使软件包、类和成员信息附带 HTML 元标记
-stylesheetfile <路径>            用于更改生成文档的样式的文件
-docencoding <名称>               输出编码名称