javadoc入门

斌斌 (给我写信)
原创博文(http://blog.csdn.net/binbinxyz),转载请注明出处

java凝视

java里面有两种类型的凝视。一种是以“/*”起头,以“*/”结尾。并能够跨越多行的凝视。例如以下:

/*
* 这是一段凝视。
* 它跨越了多行
*/

还有一种是以“//”开头的凝视。也叫单行凝视,格式例如以下:

// 这是一个单行凝视

凝视文档

注:本节内容摘自java编程思想第四版2.8.1凝视文档章节

对于java语言,最体贴的一项设计就是人们也须要考虑程序的文档化问题。

而对程序的文档化。最大的问题莫过于对文档的维护。若文档与代码分离。那么每次改变代码后都要改变文档,这无疑会变成相当麻烦的一件事情。解决办法看起来似乎非常easy:将代码同文档“链接”起来。为达到这个目的,最简单的方法是将全部内容都置于同一个文件。然而,为使一切都整齐划一,还必须使用一种特殊的凝视语法,以便标记出特殊的文档;另外还须要一个工具,用于提取这些凝视,并按有价值的形式将其展现出来。这些都是Java必须做到的。

用于提取凝视的工具叫作javadoc。它採用了部分来自Java编译器的技术。查找我们置入程序的特殊凝视标记。

它不仅提取由这些标记指示的信息,也将毗邻凝视的类名或方法名提取出来。

这样一来,我们就可用最轻的工作量,生成十分专业的程序文档。

javadoc输出的是一个HTML文件,可用自己的Web浏览器查看。该工具同意我们创建和管理单个源文件,并生动生成实用的文档。因为有了javadoc。所以我们可以用标准的方法创建文档。并且因为它很方便,所以我们能轻松获得全部Java库的文档。

javadoc案例

【实验环境】

MyEclipse 10.0 + jdk 1.6.0_13

【实验步骤】

一、新建一个java项目doc。

二、新建一个java文件org.hbin.JavaDocTest.java。并加入类凝视。例如以下图:

javadoc入门

watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQvYmluYmlueHl6/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/SouthEast" alt="">

三、在命令行工具中打开该项目src所在路径,使用javadoc命令导出java文档凝视。

命令例如以下:

> javadoc org/hbin/JavaDocTest.java

执行效果例如以下图:

javadoc入门

刷新项目。生成的文档文件夹结构例如以下:

javadoc入门

此时。文档与源代码混在一起。不便于管理维护。能够加入-d參数来指定输出文件的目标文件夹。

命令例如以下:

> javadoc -d ../doc org/hbin/JavaDocTest.java

例如以下图:

javadoc入门

javadoc入门

watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQvYmluYmlueHl6/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/SouthEast" alt="">

此时。打开项目中doc文件夹下的index.html文件就可以看到我们刚刚生成的文档结构。例如以下图:

javadoc入门

watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQvYmluYmlueHl6/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/SouthEast" alt="">

四、參考以上三个步骤,你已经能够生成自己的凝视文档了。但假设你的凝视中包括中文或其它非英文字符,那么它可能会乱码的。此时。能够通过-charset和-encoding參数来指定编码。-charset參数指定查看生成html的编码,即在html文档中加入<META http-equiv="Content-Type" content="text/html; charset=UTF-8">。而-encoding參数指定源文件编码。

命令例如以下:

> javadoc -charset UTF-8 -encoding UTF-8 -d ../doc org/hbin/JavaDocTest.java

javadoc入门

watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQvYmluYmlueHl6/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/SouthEast" alt="">

版权声明:本文博主原创文章,博客,未经同意不得转载。

上一篇:boostrap-非常好用但是容易让人忽略的地方------input-group-btn


下一篇:[Python学习笔记][第五章Python函数设计与使用]