javadoc 格式和相关文章

转载 2007年09月23日 11:20:00

JAVADOC语法
我们在开发JAVA程序中, 可以使用Javadoc来进行程序文档的整理, 当程序编写完成, 利用Java自带的JavaDoc工具就可以生成规范的API说明手册. 下面是我自己整理的一些语法:
书写格式:
/** <- 这里一定要用两个星号, 否则会被认为是普通注释的
* ........
*/
public int getCount() { .......
Javadoc只能为public,protected两种权限的类成员进行处理注释文档。当然也可以使用-private参数强制进行处理, 我们可以在注释中嵌入HTML个标记来丰富最后文档的显示, 因为Javadoc最后生成的文档就是HTML.

/**
* 一些参数列表<p>
*
* @see 类名
* @see 完整类名
* @see 完整类名#方法
*
* @param 参数名 说明
* @return 说明
* @exception 完整类名 说明
* @deprecated
*
* @version 版本信息
* @author 作者名
*/
说明:
@see : 就是文档中的 参见xx 的条目, 其实就是超链接.

一般来说, 文档有三种类型: 类注释, 变量注释, 方法注释, 这三中类型的注释除了都可以包含 @see 参数外, 其它所包含的参数是不同的.
1. 类注释
类注释是写在类前面的, 用来说明类的一些情况, 可以包涵 @version,@author参数, 但Javadoc缺省情况下不处理, 也就是说不在最后文档中出现的, 为了使用这些信息, 我们可以加入参数 -version和 -author来强制输出到最后的文档中.
2. 变量注释
变量注释写在变量前面, 只能包含 @see 参数
3. 方法注释
方法注释可以包括
@param : 参数名是指参数列表内的标识符, 说明就是一些解释性质的文字, 可以多行.
@return : 返回值的说明, 可以多行
@exception : 完整类名应该明确指定一个违例类的名字,它是在其它某个地方定义好的。而说明则阐述为什么这种特殊类型的违例会在方法调用中出现。说明可以多行
@deprecated : 指出一些旧功能已由改进过的新功能取代。该标记的作用是建议用户不必再使用一种特定的功能,因为未来改版时可能摒弃这一功能。若将一个方法标记为@deprecated,则使用该方法时会收到编译器的警告。
 

Ashley J.S Mills

<


1.?JavaDocHow to Write Doc Comments for the JavadocTM Tool, an API should describe “all aspects of the behavior of each method on which a caller can rely”. One generally uses JavaDoc to document things such as Classes, Interfaces and Methods but one can theoretically use it for anything written in Java by defining custom tags and creating custom DocLets.

JavaDoc is a tool which extracts information from a Java source file to create an API. It is specifically oriented toward this kind of documentation. To quote

JavaDoc is written within the Java source code for a particular project and then the javadoc tool is used to extract the JavaDoc-marked-up sections and create the HTML files that comprise the JavaDoc output.

2.?Installationhttp://java.sun.com/j2se/. You should be capable of following the instructions that come with this to install it; see Configuring A Windows Working Environment and Configuring A Unix Working Environment.

JavaDoc comes with the J2SE (Java 2 Platform Standard Edition), available from

 

The general format of a JavaDoc marked up section is:

/**
 * This is the description part of the doc comment.
 *
 * Additional details
 *
 * @tag1 Tag Content
 * @tag2 Tag Content
 *   .
 *   .
 *   .
 */
      

Take notice of the spacing used, the tags section must be separated from the description by a single blank line. The content of the comment starts one space in from the left hand edge of the comment. Tag lists may be separated into logical blocks by inserting a blank line. Lines should preferably be below 80 columns in width. New paragraphs can be specified by using the <p> tag.

The first sentence should summarize the overall behaviour of the Class, Interface or Method being described. It should be terminated with a full stop followed by either a space, tab or newline, it may span more than one line. To include multiple full stops in the first sentence, make sure that the ones that do not signify the end of the first sentence are not followed by a space, tab or newline. This can be achieved by using the HTML entity &nsbp;:

 /**
  * This is the part of the first sentence.&nsbp;This is still part of the first sentence. This is not.
  *    
  */
      

One should write from the perspective of the third person:

 /**
  * Correct   - Returns an Integer representing the mean of the numbers provided as parameters.
  *
  *             It has the special feature of blah blah blah...
  *
  * Incorrect - This method returns an Integer representing the mean of the numbers you provide as parameters. 
  *
  *             This has the special feature of blah blah blah...
  */
      

Tag inclusion should accord to the following order:

 


*?@author???????(classes?and?interfaces?only,?required)
*?@version??????(classes?and?interfaces?only,?required)
*???????????????
*?@param????????(methods?and?constructors?only)
*?@return???????(methods?only)
*?@exception????(@throws?is?a?synonym?added?in?Javadoc?1.2)
*?@see??????????
*?@since????????
*?@serial???????(or?@serialField?or?@serialData)
*?@deprecated
????????

 

When using Java code in a description, one should use <code>blah</code>:

*
* Returns <code>true</code> if blah otherwise returns <code>false</code>
*
      

A description may contain any HTML tags:

/**
 * This is the <strong>description</strong> part of the doc comment.
 * <p>
 *   blah blah blah blah blah
 *   blah blah <b>blah</b> <i>blah</i>blah
 * </p>
 * <pre>
 *     blah
 * blah    blah
 * </pre>
 * 
 * @author Ashley <strong>Mills</strong>
 * @version 1.2
 */
public class test {
         .
         .
         .
      

 

The command javadoc is used to generate the JavaDoc output:

javadoc blah.java

Creates JavaDoc for the file blah.java.

javadoc *.java

Creates JavaDoc for all java files in the current directory.

javadoc -help

Displays the command line options (so does not providing any).

JavaDoc does not automatically link to the real online API, to achieve this one has to utilise the -link option provided by StandardDoclet. Assuming one desires to link to the Java 1.4 API, one would use:

        javadoc -link http://java.sun.com/j2se/1.4/docs/api *.java
      

This causes all references to Java 1.4 classes in the generated HTML to be resolved.

[Tip] Tip

Use the -d option to direct generated JavaDoc to a specific directory.

 

@author author name

Specifies the author of the class or interface:

 * 
 * @author Jimmy Petronas
 * @author Mickey Block 
 * @author Sally Finch
 *
      

Not included in generated HTML using standard Doclet, unless turned on by specifying -author option when running javadoc

 

@version version information

Adds version information to a class.

*
* @version 1.2
*
      

Only one per class or interface allowed. Not included in generated HTML using standard Doclet, unless turned on by specifying the -version option when running javadoc.

 

@param parameter-name description

Adds a parameter to the parameter list.

/**
 * Returns the product of two integers.
 *
 * @param int operand one 
 * @param int operand two
 * @return an int 
 */
public int mul(int a, int b) {
   return a*b;
}
      

 

@return description of return value

Describes the value returned from a method.

*
* @return A new BlahBlah Object with a field size of 100.
*
      

 

@exception class-name description

Describes the exceptions thrown by the constructor, method, class or interface. class-name is the name of the exception.

   /**
    * Replaces test().
    * @throws BlahException unless blah blah blah
    * @exception BlahBlahException 
    */
   public test(int i) {
   }
      

 

@see classname

Adds a hyperlink to the section referenced by the classname supplied.

/**
 * Returns the product of the squares of a and b.
 *
 * @see #mul
 *
 * @param int operand one 
 * @param int operand two
 * @return an int 
 */
   public int squaredMul(int a, int b) {
      return mul(mul(a,a),mul(b,b));
   }
      

The classname can be local like this example, prefixed with a hash '#' or a fully qualified class name likejava.lang.String or java.lang.String#charAt.

 

@since since-text

Specifies from which version of Java this class, method or interface has been available from.

*
* @since JDK1.4
*
      

 

@deprecated deprecated-text

Marks a class, interface or method as deprecated.

/**
 * @deprecated Replaced by <code>test(int)</code>
 * @see #test(int)
 */
public test() {
}

/**
 * Replaces test().
 */
public test(int i) {
}
      

 

More detail pertaining to the available tags can be found at the JavaDoc reference page:

Here is a simple example showing a few of the features of JavaDoc:

/**
 * Represents a "fuzzy" integer, in that the integer is
 * not exact, but is instead specified as being between a range.
 *
 * @author Ashley Mills
 * @version 1.0b
 */
public class FuzzyInteger {
   private int lowerVal, upperVal;

   /**
    * Creates a new <code>FuzzyInteger</code> object based on the
    * range specified.
    * 
    * @param lowerVal The lowest value that the integer could be.
    * @param upperVal The highest value that the integer could be.
    */
   public FuzzyInteger(int lowerVal, int upperVal) {
      this.lowerVal = lowerVal;
      this.upperVal = upperVal;
   }

   /**
    * Doubles the value of the <code>FuzzyInteger</code>.
    */
   public void doubleFuzzy() {
      lowerVal = lowerVal+lowerVal;
      upperVal = upperVal+upperVal;
   }
}
    

 

javadoc注释模板设置及详解

设置注释模板的入口: Window->Preference->Java->Code Style->Code Template 然后展开Comments节点就是所有需设置注释的元素啦。现就每一个元素逐一...
  • projectNo
  • projectNo
  • 2017年08月01日 10:02
  • 440

java中的注释规范,生成javadoc

java中的注释,大家应该已经很熟悉了。 文档注释可以用于对类、属性、方法等进行说明。写文档注释时除了需要使用 /** .... */ 限定之外,还需要注意注释内部的一些细节问题。 ...
  • l454822901
  • l454822901
  • 2016年09月23日 15:54
  • 2659

JavaDoc生成API详解

开发者文档(API)应该在开发的同时在代码中写好,这就是使用Javadoc的原因。每一个Java程序员都应该熟练掌握。...
  • fanxiaobin577328725
  • fanxiaobin577328725
  • 2016年09月25日 11:02
  • 5937

python相关文章导引

python 总述 python运算 python 数据结构 列表 元组 字典 字符串 异常处理 文件操作 细节 排序 数据库操作 异常 语法细节 常见库的使用 time loggingpython ...
  • TheSnowBoy_2
  • TheSnowBoy_2
  • 2017年02月17日 23:09
  • 547

如何最方便的查看javadoc

www.docjar.com是一个javadoc的搜索引擎,别的不说,只看界面就知道这些jar都是手工搜集而成(lastest updates),世界上已有的jar和新版本的jar就凭手工收集是无论...
  • u013497460
  • u013497460
  • 2014年03月04日 23:47
  • 1506

eclipse设置本地Javadoc API路径

在线的javadoc访问地址: http://download.oracle.com/javase/7/docs/api/   javadoc(JDK 7 Documentation)下载地址:...
  • D_reamW_eaver
  • D_reamW_eaver
  • 2013年07月12日 15:31
  • 1320

你不知道的Eclipse用法:使用Javadoc导出项目的API文档

使用Javadoc导出项目的API文档
  • ZJDWHD
  • ZJDWHD
  • 2016年08月31日 15:32
  • 1826

[Java]简易使用JavaDoc生成说明文档

相信大家都已经看过了不少说明文档,例如Java API、Android API,它们无疑都是这样的:...
  • u011596810
  • u011596810
  • 2016年03月08日 14:48
  • 7744

AdnroidStudio下javaDoc任务相关配置

这两天用AndroidStudio打包工程,中间涉及到task javaDoc,记录下对这方面的相关配置:   1.如果工程中涉及到中文的话,在执行javaDoc任务时可能会报中文编码问题,这个问题在...
  • IT_Phoenix
  • IT_Phoenix
  • 2016年05月30日 16:41
  • 467

Java IDE中设置作者日期等Javadoc注释信息

在Java的IDE(Integrated Development Environment,集成开发环境)中,如Eclipse、Spring Tool Suite、IntelliJ IDEA等,...
  • czh500
  • czh500
  • 2016年06月21日 19:38
  • 3857
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:javadoc 格式和相关文章
举报原因:
原因补充:

(最多只允许输入30个字)