JavaDoc注释的使用

2009-06-16 11:29 woaidongmao   cpp博客   我要评论(0)  字号： T  |   T
一键收藏，随时查看，分享好友！

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

AD：

 

Javadoc是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形式程序的开发文档了。 
Javadoc输出的是一些HTML文件，我们可以通过WEB浏览器来查看它。 
Javadoc的语法： 
所有Javadoc都只能源于/**开始和*/结束。使用javadoc有二种方式：一种是嵌入HTML；另一种是使用文档标签。所谓文档标签就是一些以 “@”开头的命令，且“@”要置于注释行的最前面。而“行内文档标签”则可以出现在Javadoc注释中的任何地方，它们也是以“@”字符开头，但要括在共括号内。 
Javadoc只能为public或者protected成员进行文档注释。private和包内访问的成员的注释会被忽略掉。这样做是有道理的，因为只有public和protected成员才能在文件之外被使用，这也体现了封装性的优点。 
嵌入HTML： 
Javadoc将HTML代码嵌入到所生成的HTML文件中。这样能充分利用HTML的功能。比如：

 
    
  1. /**   
  2. *<b>   
  3. *this is my test program;   
  4. *</b>   
  5. */  
 
    
但一般我们不要在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：
 
    
 
    
  1. import java.util.*;   
  2. /** 这是一个为了测试Javadoc而专门写的类   
  3. * 功能是打印字符串 HelloWorld   
  4. * @author AuthorName   
  5. * @version 1.0   
  6. */   
  7. public class JavaDocTest {   
  8.  
  9. /** 这里的main函数，作为java程序的入口   
  10.   * @param 参数为一个String对象数组   
  11.   * @return 没有返回值的内容   
  12.   * @exception exceptions 没有异常被抛出   
  13.   */   
  14. public static void main(String[] args){   
  15.      System.out.print("HelloWorld!");       
  16. }   
  17. }  
 
    
如果使用eclipse的话，完全不需要背这些标签。在需要注释的地方打上/**之后，再打@符号eclipse会自动显示所支持的标签供选择。 
 同样在生成HTML文档时也可以利用eclipse的export功能直接导出，否则用javadoc手工来生成的话是件相当痛苦的事情。
 
    
1.编写一小段程序，体会文档注释的用法，并通过文档生成工具提取文档注释，形成程序文档。
 
    
代码如下：
 
    
 
    
  1. //： Property.java  
  2.  
  3. import java.util.*;  
  4.  
  5. /** The first example program in "Thinking in Java."   
  6.  
  7.  * Lists system information on current machine.  
  8.  
  9.  * @author Bruce Eckel  
  10.  
  11.  * @author http：//www.EckelObjects.com/Eckel  
  12.  
  13.  * @version 1.0  
  14.  
  15.  */ 
  16.  
  17. public class Property {  
  18.  
  19.     /** Sole entry point to class & application  
  20.  
  21.      * @param args Array of string arguments  
  22.  
  23.      * @exception No exceptions are thrown   
  24.  
  25.      */ 
  26.  
  27.     public static void main(String args[]) {  
  28.  
  29.        System.out.println(new Date());  
  30.  
  31.        System.getProperties().list(System.out);  
  32.  
  33.        System.out.println("--- Memory Usage：");  
  34.  
  35.        Runtime rt = Runtime.getRuntime();  
  36.  
  37.        System.out.println("Total Memory = "   
  38.  
  39.                          + rt.totalMemory()  
  40.  
  41.                          + " Free Memory = "   
  42.  
  43.                          + rt.freeMemory());  
  44.     }}  
 
    
利用Myeclipse生产javadoc文档的步骤如下：
 
    
1.选择File->Export->javadoc，下一步。
 
    
2.Javadoc comand选择JDK的bin目录下的javadoc.exe。选择要生成的源代码和javadoc保存的目的路径，下一步。
 
    
3.Document title输入标题，下一步。
 
    
4.overview输入启动指定的overview文件路径，Extra Javadoc options输入
 
    
-windowtitle 'Type B Monitor'[浏览器显示标题]
 
    
-bottom <center>Travelsky</center>[底部显示文本]，下一步。