在IntelliJ IDEA中为自己设计的类库生成JavaDoc的方法示例

因为某个项目需要,为团队其他兄弟姐妹开发了一个 XML 分析处理器,并将其设计为一个类库,提供相应的 API 接口。为了方便大家的使用,需要生成对应的 JavaDoc 帮助文档,就像 JavaSE 标准库提供的 JavaDoc 那样。我的开发工具为 IntelliJ IDEA 12.1.6,本身提供了很好的 JavaDoc 生成功能,以及标准 JavaDoc 注释转换功能,其实质是在代码编写过程中,按照标准 JavaDoc 的注释要求,为需要暴露给使用者的类、方法以及其他成员编写注释。然后使用 IDEA 的功能自动调用 javadoc.exe(JDK 自带的工具)根据源代码中的注释内容自动生成 JavaDoc 文档(超文本格式)。标准 JavaDoc 的注释规则,大家可以在网上很容易搜索到,这里有几点倒是要特别注意一下:

1.IDEA 的 JavaDoc 生成功能在菜单 Tools->Generate JavaDoc 项里面。

2.点击上述菜单项后,会出现生成 JavaDoc 的对话框,一般的选项都很直观,不必细说。但是要注意生成 JavaDoc 的源代码对象的选择,一般以模块(Module)为主,必要时可以单独选择必要的 Java 源代码文件,不推荐以 Project 为 JavaDoc 生成的源范围。

3.里面有一个 Locale 可选填项,表示的是需要生成的 JavaDoc 以何种语言版本展示,根据 javadoc.exe 的帮助说明,这其实对应的就是 javadoc.exe 的 -locale 参数,如果不填,默认可能是英文或者是当前操作系统的语言,既然是国人,建议在此填写 zh_CN,这样生成的 JavaDoc 就是中文版本的,当然指的是 JavaDoc 的框架中各种通用的固定显示区域都是中文的。你自己编写的注释转换的内容还是根据你注释的内容来。

4.还有一个“Other command line arguments:”可选填项,非常重要,是填写直接向 javadoc.exe 传递的参数内容。因为有一些重要的设置,只能通过直接参数形式向 javadoc.exe 传递。这里必须要填写如下参数:

-encoding UTF-8 -charset UTF-8 -windowtitle "你的文档在浏览器窗口标题栏显示的内容" -link http://docs.oracle.com/javase/7/docs/api

5.第一个参数 -encoding UTF-8 表示你的源代码(含有符合 JavaDoc 标准的注释)是基于 UTF-8 编码的,以免处理过程中出现中文等非英语字符乱码;第二个参数 -charset UTF-8 表示在处理并生成 JavaDoc 超文本时使用的字符集也是以 UTF-8 为编码,目前所有浏览器都支持 UTF-8,这样最具有通用性,支持中文非常好;第三个参数 -windowtitle 表示生成的 JavaDoc 超文本在浏览器中打开时,浏览器窗口标题栏显示的文字内容;第四个参数 -link 很重要,它表示你生成的 JavaDoc 中涉及到很多对其他外部 Java 类的引用,是使用全限定名称还是带有超链接的短名称,举个例子,我创建了一个方法 public void func(String arg),这个方法在生成 JavaDoc 时如果不指定 -link 参数,则 JavaDoc 中对该方法的表述就会自动变为 public void func(java.lang.String arg),因为 String 这个类对我自己实现的类来讲就是外部引用的类,虽然它是 Java 标准库的类。如果指定了 -link http://docs.oracle.com/javase/7/docs/api 参数,则 javadoc.exe 在生成 JavaDoc 时,会使用 String 这样的短名称而非全限定名称 java.lang.String,同时自动为 String 短名称生成一个超链接,指向官方 JavaSE 标准文档 http://docs.oracle.com/javase/7/docs/api 中对 String 类的详细文档地址。-link 实质上是告诉 javadoc.exe 根据提供的外部引用类的 JavaDoc 地址去找一个叫 package-list 的文本文件,在这个文本文件中包含了所有外部引用类的全限定名称,因此生成的新 JavaDoc 不必使用外部引用类的全限定名,只需要使用短名称,同时可以自动创建指向其外部引用 JavaDoc 中的详细文档超链接。每个 JavaDoc 都会在根目录下有一个 package-list 文件,包括我们自己生成的 JavaDoc。

JavaDoc 生成完毕,即可在其根目录下找到 index.html 文件,打开它就可以看到我们自己的标准 JavaDoc API 文档啦。

javadoc常用标识

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

到此这篇关于在IntelliJ IDEA中为自己设计的类库生成JavaDoc的方法示例的文章就介绍到这了,更多相关IDEA生成JavaDoc内容请搜索我们以前的文章或继续浏览下面的相关文章希望大家以后多多支持我们!

(0)

相关推荐

  • 详解IDEA自定义注释模板(javadoc)

    最近要开始做项目了,项目规定了方法注释模板,那么idea是如何自定义注释模板的呢? 有两种解决方案: 1.安装Jindent插件,好处是自动生成模板,但是很可惜本人安装失败,设置好以后不知道为什么无法Apply,可能是我的版本问题,失败的同学请看方案二. 2.Jindent插件下载:http://plugins.jetbrains.com/plugin/2170?pr=idea,也可以直接在idea中在线安装,类似eclipse的在线install2.使用idea自带的Live Template

  • 在IntelliJ IDEA中为自己设计的类库生成JavaDoc的方法示例

    因为某个项目需要,为团队其他兄弟姐妹开发了一个 XML 分析处理器,并将其设计为一个类库,提供相应的 API 接口.为了方便大家的使用,需要生成对应的 JavaDoc 帮助文档,就像 JavaSE 标准库提供的 JavaDoc 那样.我的开发工具为 IntelliJ IDEA 12.1.6,本身提供了很好的 JavaDoc 生成功能,以及标准 JavaDoc 注释转换功能,其实质是在代码编写过程中,按照标准 JavaDoc 的注释要求,为需要暴露给使用者的类.方法以及其他成员编写注释.然后使用

  • 在IntelliJ IDEA中创建和运行java/scala/spark程序的方法

    本文将分两部分来介绍如何在IntelliJ IDEA中运行Java/Scala/Spark程序: 基本概念介绍 在IntelliJ IDEA中创建和运行java/scala/spark程序 基本概念介绍 IntelliJ IDEA 本文使用版本为: ideaIC-2020.1 IDEA 全称 IntelliJ IDEA,是java编程语言开发的集成环境.IntelliJ在业界被公认为最好的java开发工具,它的旗舰版本还支持HTML,CSS,PHP,MySQL,Python等,免费版只支持Jav

  • IntelliJ IDEA中SpringBoot项目通过devtools实现热部署的方法

    简要几个步骤: 一.添加依赖 <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-devtools</artifactId> <optional>true</optional> </dependency> 二.开启热部署 <build> <plugins> <plugin&

  • logback中显示mybatis查询日志文件并写入的方法示例

    目录 在logback中显示mybatis查询日志 一.配置文件 二.定制包的日志level 三.通过logback-spring.xml文件 将操作数据库sql记录到日志文件中 网上看了很多篇文章关于如何配置mybatis的logback日志的,复杂的简单的都有,但是有用的没几个,耽误了很多时间.通过对logback的学习,以下方式是一定可行的,希望可以为大家节省点时间.通常我们可以通过如下配置将操作数据库的sql语句打印到控制台上,但是如何将这些sql语句记录到日志文件中方便我们查询问题呢?

  • Python开发中爬虫使用代理proxy抓取网页的方法示例

    本文实例讲述了Python开发中爬虫使用代理proxy抓取网页的方法.分享给大家供大家参考,具体如下: 代理类型(proxy):透明代理 匿名代理 混淆代理和高匿代理. 这里写一些python爬虫使用代理的知识, 还有一个代理池的类. 方便大家应对工作中各种复杂的抓取问题. urllib 模块使用代理 urllib/urllib2使用代理比较麻烦, 需要先构建一个ProxyHandler的类, 随后将该类用于构建网页打开的opener的类,再在request中安装该opener. 代理格式是"h

  • C#实现输入10个数存入到数组中并求max和min及平均数的方法示例

    本文实例讲述了C#实现输入10个数存入到数组中并求max和min及平均数的方法.分享给大家供大家参考,具体如下: using System; using System.Collections.Generic; using System.Linq; using System.Text; namespace ConsoleApplication1 { class Program { static void Main(string[] args) { int nu1, max,min,number;

  • Android开发中button按钮的使用及动态添加组件方法示例

    本文实例讲述了Android开发中button按钮的使用及动态添加组件方法.分享给大家供大家参考,具体如下: MainActivity.java package com.example.lab2; import android.os.Bundle; import android.app.Activity; import android.content.Context; import android.view.Menu; import android.view.View; import andro

  • IntelliJ IDEA中显示和关闭工具栏与目录栏的方法

    工具栏:就是上面有个好多的快捷按钮的那个栏,比如撤销,上传,下载设置,扳手按钮,等等. 目录栏:就是刚刚装的时候,这个会显示,但是不知道怎么关闭,但是这个又没什么用. 如图: 就是对应的几个按钮,自己试试就知道什么效果了. 总结 以上就是这篇文章的全部内容了,希望本文的内容对大家的学习或者工作具有一定的参考学习价值,谢谢大家对我们的支持.如果你想了解更多相关内容请查看下面相关链接

  • IntelliJ IDEA中打开拼写检查与忽略提示曲线的方法

    他可以让你的代码看起来很规范. Spellchecker inspection helps locate typos and misspelling in your code, comments and literals, and fix them in one click. 拼写检查器检查有助于定位错别字和拼写错误的代码,注释和文字,并把它们固定在一个点击. 重点就是规范,不至于看着很水,到处都是警告.因为拼写错误可能是因为你的单词真的写错了,丢人吧.或者就是没有驼峰发命名 总之这么个样式的代

  • Go语言中利用http发起Get和Post请求的方法示例

    关于 HTTP 协议 HTTP(即超文本传输协议)是现代网络中最常见和常用的协议之一,设计它的目的是保证客户机和服务器之间的通信. HTTP 的工作方式是客户机与服务器之间的 "请求-应答" 协议. 客户端可以是 Web 浏览器,服务器端可以是计算机上的某些网络应用程序. 通常情况下,由浏览器向服务器发起 HTTP 请求,服务器向浏览器返回响应.响应包含了请求的状态信息以及可能被请求的内容. Go 语言中要请求网页时,使用net/http包实现.官方已经提供了详细的说明,但是比较粗略,

随机推荐