[java] 注释以及javadoc使用简介-汇率换算器的实现-插曲3

[java] 注释以及javadoc使用简介-汇率换算器的实现-插曲3

Table of Contents

• 1 系列文章地址
• 2 本文动机介绍
• 3 javadoc介绍
• 4 注释分类–按范围分
• 5 常用的标签
• 6 针对包的注释
• 7 针对类和接口的注释
• 8 针对方法的注释
• 9 其他字段的注释
• 10 在"汇率转换器"源代码中添加注释
• 11 执行javadoc, 并且使得中文正常显示

1 系列文章地址

• java 汇率换算器的实现(1)
• java 汇率换算器的实现(2)
• java 汇率换算器实现-插曲1-正则表达式(1)
• java 汇率换算器的实现(3)
• java jsoup使用简介-汇率换算器实现-插曲2

2 本文动机介绍

虽然在写代码的过程中还是会注意添加一些注释, 但是仍然没有一个规范, 因此这里针对javadoc工具中要求的注释规范进行了简单的了解, 并将它应用到"汇率换算器"实现的代码中.

3 javadoc介绍

javadoc是将java源代码中中的注释, 按照相关的规范转化为html格式的api文档的文档生成器. 在注释过程中, 可以使用html相关的标签如:

1. ..., ... 用于强调
2. ... 用于添加代码片断
3.  包含图片
4. 
 空一行
5. ... 添加链接

4 注释分类–按范围分

按照范围可以将注释分类为:

• 包
• 类以及接口
• 方法
• 其他字段

5 常用的标签

@author name     -> 作者
@version text    -> 版本号
@since text      -> 如: @since version 1.7.1
@deprecated text -> 说明该方法或类不建议使用, 如: @deprecated Use setVisibile(true) instead
@see link        -> 链接跳转到近似内容处, 通常是具体的类和方法, 如: @see com.rateexchange.Employee#raiseSalary(double)

6 针对包的注释

想要产生针对包的注释, 需要在每个包的目录下建立一个新的文件: package.html , 并且所有的注释文字都包括在…内.

7 针对类和接口的注释

恰好在类之前的注释都被解释为类的注释, 针对接口的情况也类似. 如jsoup.Node.java中的注释示例:

/**
 The base, abstract Node model. Elements, Documents, Comments etc are all Node instances.

 @author Jonathan Hedley, jonathan@hedley.net 
*/
public abstract class Node implements Cloneable {
    ...
}

8 针对方法的注释

@parm variable description -> 参数注释
@return description        -> 返回值注释
@throws class description  -> 抛出的异常注释

举例说明, 如jsoup.Node.java中的注释示例:

/**
 * get an absolute url from a url attribute that may be relative (i.e. an <a href> or
 * <img src>).
 * 

 * e.g.: string absurl = linkel.absurl("href");
 * 

 * if the attribute value is already absolute (i.e. it starts with a protocol, like
 * http:// or https:// etc), and it successfully parses as a url, the attribute is
 * returned directly. otherwise, it is treated as a url relative to the element's {@link #baseuri}, and made
 * absolute using that.
 * 

 * as an alternate, you can use the {@link #attr} method with the abs: prefix, e.g.:
 * string absurl = linkel.attr("abs:href");
 *
 * @param attributekey the attribute key
 * @return an absolute url if one could be made, or an empty string (not null) if the attribute was missing or
 * could not be made successfully into a url.
 * @see #attr
 * @see java.net.url#url(java.net.url, string)
 */
public string absurl(string attributekey) { 
    ...
}

9 其他字段的注释

如对静态变量的注释, 如下:

/**
   The "Hearts" card suit
*/
public static final int HEARTS = 1;

10 在"汇率转换器"源代码中添加注释

具体内容将github: https://github.com/stupidgrass/RateExchange

11 执行javadoc, 并且使得中文正常显示

javadoc -d doc -sourcepath src/ -charset utf-8 -encoding utf-8 -docencoding utf-8 com.cnblogs.grassandmoon

Date: 2014-05-16 Fri

Author: Zhong Xiewei

Org version 7.8.11 with Emacs version 24