woaidongmao

文章均收录自他人博客,但不喜标题前加-[转贴],因其丑陋,见谅!~
随笔 - 1469, 文章 - 0, 评论 - 661, 引用 - 0
数据加载中……

JavaDoc注释使用

    JavadocSun公司提供的一个技术,它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说,只要在编写程序时以一套特定的标签作注释,在程序编写完成后,通过Javadoc就可以同时形式程序的开发文档了。
Javadoc
输出的是一些HTML文件,我们可以通过WEB浏览器来查看它。
Javadoc
的语法:
所有Javadoc都只能源于/**开始和*/结束。使用javadoc有二种方式:一种是嵌入HTML;另一种是使用文档标签。所谓文档标签就是一些以 “@”开头的命令,且“@”要置于注释行的最前面。而行内文档标签则可以出现在Javadoc注释中的任何地方,它们也是以“@”字符开头,但要括在共括号内。
Javadoc
只能为public或者protected成员进行文档注释。private和包内访问的成员的注释会被忽略掉。这样做是有道理的,因为只有publicprotected成员才能在文件之外被使用,这也体现了封装性的优点。
嵌入HTML:
Javadoc
HTML代码嵌入到所生成的HTML文件中。这样能充分利用HTML的功能。比如:
/**
*<b>
*this is my test program;
*</b>
*/
但一般我们不要在HTML里使用标题,如<h1><hr>,因为Javadoc会插入自己的标题,我们的标题可能会干扰它。
常用的标签:
1) @see:
引用其它类的文档,相当于超链接,Javadoc会在其生成的HTML文件中,将@see标签链到其他的文档
@see classname
这样在生成的文档中会出现"See Also"的超链蛸。但是Javadoc不去检查你的超链接是否有效。
2) {@link package.class#member label}
@See的功能一样,只是用label作主超链接,而不是用"see also"
3) {@docRoot}
:标签产生 到文档根目录的相对路径,用于文档树页面的显式超链接
4) {@inheritDoc}:
标签从当前这个类的最直接的基类中继承相关文档到当前的文档注释中。
5) @version
:使用方法为@version 2.2.1.2...
      2.2.1.2...
是我们作的版本说明信息
6) @author:
使用方法为 @author PowerFedora powpro@hotmail.com
     
也就是说我们可以在@author后加上作者名字,email等联系方式
7) @since
:这个标签允许你指定程序最早使用的版本。
     
比如我们看JDK Document里的每个类最后都会说明从JDK哪个版本开始启用。
8) @param
@param name 用于输入客户的姓名
      @param
后面是方法的参数,以及相应的说明
     
我们可以使用任意数量的此标签,每个参数都可以有这样一个标签
9) @return this is description
      @return
后面是描述返回值的含义,可以延续几行。
10) @throws fully-qualified-class-name description
      fully-qualified-class-name
为异常类的完整名字,
     
description告诉你为什么此异常会在方法中调用出现。
11) @deprecated:
用于指出一些旧特性已由改进的新特性所取代,建议用户不要再使用旧特性。

Sample


import java.util.*;
/**
这是一个为了测试Javadoc而专门写的类
*
功能是打印字符串 HelloWorld
* @author AuthorName
* @version 1.0
*/
public class JavaDocTest {

/**
这里的main函数,作为java程序的入口
  * @param
参数为一个String对象数组
  * @return
没有返回值的内容
  * @exception exceptions
没有异常被抛出
  */
public static void main(String[] args){
     System.out.print("HelloWorld!");    
}
}
如果使用eclipse的话,完全不需要背这些标签。在需要注释的地方打上/**之后,再打@符号eclipse会自动显示所支持的标签供选择。
同样在生成HTML文档时也可以利用eclipseexport功能直接导出,否则用javadoc手工来生成的话是件相当痛苦的事情。

========================================================================

========================================================================

1.编写一小段程序,体会文档注释的用法,并通过文档生成工具提取文档注释,形成程序文档。

代码如下:

//: Property.java

import java.util.*;

 

/** The first example program in "Thinking in Java."

 * Lists system information on current machine.

 * @author Bruce Eckel

 * @author http://www.EckelObjects.com/Eckel

 * @version 1.0

 */

public class Property {

    /** Sole entry point to class & application

     * @param args Array of string arguments

     * @exception No exceptions are thrown

     */

    public static void main(String args[]) {

       System.out.println(new Date());

       System.getProperties().list(System.out);

       System.out.println("--- Memory Usage:");

       Runtime rt = Runtime.getRuntime();

       System.out.println("Total Memory = "

                         + rt.totalMemory()

                         + " Free Memory = "

                         + rt.freeMemory());

    }

} ///:~

利用Myeclipse生产javadoc文档的步骤如下:

1.选择File->Export->javadoc,下一步。

2.Javadoc comand选择JDKbin目录下的javadoc.exe。选择要生成的源代码和javadoc保存的目的路径,下一步。

3.Document title输入标题,下一步。

4.overview输入启动指定的overview文件路径,Extra Javadoc options输入

-windowtitle 'Type B Monitor'[浏览器显示标题]

-bottom <center>Travelsky</center>[底部显示文本]

下一步。

posted on 2009-06-15 11:13 肥仔 阅读(2234) 评论(0)  编辑 收藏 引用 所属分类: Web-后台


只有注册用户登录后才能发表评论。
网站导航: 博客园   IT新闻   BlogJava   知识库   博问   管理