Usage of Javadoc Comments

Usage of Javadoc Comments

 

Usage of Javadoc Comments

 

Related reading: http://blog.163.com/hui_san/blog/static/5710286720104191100389/ 

1. Java  documentation
   
   //  Comment one line
   /* ...... */  Comment several lines
   /** ...... */  Comment several lines and write them into  javadoc  documents Usually, the multi-line writing of such comments is as follows: / ** * ......... * ......... */ javadoc -d  document storage directory  -author -version  source file name.java This command compiles a file named " source file name " .java " , and store the generated document in the  directory  specified by " Document Storage Directory " . The  index.html  in the generated document is the homepage of the document. The -author  and  -version  options can be omitted.
   
   
   
   
   
   
   
   
   
   

   
   
   2. Format of  documentation comments
   
   1.  Formatting of documentation and documentation comments The generated documents are in  HTML  format, and the identifiers in these  HTML  formats are not added by  javadoc  , but are written when we write comments. For example, when a newline is required, instead of typing a carriage return, write  <br> , and if you want to segment, you should write  <p> before the segment . The text of the document comment is not directly copied to the output file  ( the  HTML  file of the document ) , but after each line is read, the leading  *  and the spaces before the * are deleted, and then input to the document  . Such as /** * This is first line. <br> ***** This is second line. <br> This is third line. */  2.  The three parts of the document comment are as follows /** * The show  method Briefly .
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   * <p>show 方法的详细说明第一行<br>
   * show 方法的详细说明第二行
   * @param b true 表示显示，false 表示隐藏
   * @return 没有返回值
   */
   public void show(boolean b) {
   frame.show(b);
   }
   
   第一部分是简述。文档中，对于属性和方法都是先有一个列表，然后才在后面一个一个的详细的说明 
   简述部分写在一段文档注释的最前面，第一个点号 (.) 之前 (包括点号)。换句话说，就是用第一个点号分隔文档注释，之前是简述，之后是第二部分和第三部分。
   
   第二部分是详细说明部分。该部分对属性或者方法进行详细的说明，在格式上没有什么特殊的要求，可以包含若干个点号。 
   * show 方法的简述.
   * <p>show 方法的详细说明第一行<br>
   * show 方法的详细说明第二行
   
   简述也在其中。这一点要记住了
   
   第三部分是特殊说明部分。这部分包括版本说明、参数说明、返回值说明等。
   * @param b true 表示显示，false 表示隐藏
   * @return 没有返回值
   

   
   三. 使用 javadoc 标记
   javadoc 标记由"@"及其后所跟的标记类型和专用注释引用组成
   javadoc 标记有如下一些：
   @author 标明开发该类模块的作者 
   @version 标明该类模块的版本 
   @see 参考转向，也就是相关主题 
   @param 对方法中某参数的说明 
   @return 对方法返回值的说明 
   @exception 对方法可能抛出的异常进行说明 
   
   @author 作者名
   @version 版本号
   其中，@author 可以多次使用，以指明多个作者，生成的文档中每个作者之间使用逗号 (,) 隔开。@version 也可以使用多次，只有第一次有效
   
   使用 @param、@return 和 @exception 说明方法
   这三个标记都是只用于方法的。@param 描述方法的参数，@return 描述方法的返回值，@exception 描述方法可能抛出的异常。它们的句法如下：
   @param 参数名参数说明
   @return 返回值说明
   @exception 异常类名说明
   
   
   四. javadoc 命令
   用法：
   　　javadoc [options] [packagenames] [sourcefiles]
   
   选项：
   
   -public 仅显示 public 类和成员 
   -protected 显示 protected/public 类和成员 (缺省) 
   -package 显示 package/protected/public 类和成员 
   -private 显示所有类和成员 
   -d <directory> 输出文件的目标目录 
   -version 包含 @version 段 
   -author 包含 @author 段 
   -splitindex 将索引分为每个字母对应一个文件 
   -windowtitle <text> 文档的浏览器窗口标题 
   
   javadoc 编译文档时可以给定包列表，也可以给出源程序文件列表。例如在 CLASSPATH 下有两个包若干类如下：
   
   　　fancy.Editor
   　　fancy.Test
   　　fancy.editor.ECommand
   　　fancy.editor.EDocument
   　　fancy.editor.EView
   
   可以直接编译类：
   javadoc fancy\Test.java fancy\Editor.java fancy\editor\ECommand.java fancy\editor\EDocument.java fancy\editor\EView.java
   
   也可以是给出包名作为编译参数，如：javadoc fancy fancy.editor
   可以自己看看这两种方法的区别
   
   到此为止javadoc就简单介绍完了，想要用好她还是要多用，多参考标准java代码(可参考JDK安装目录下的src源文件包)