[java] 注释以及javadoc使用简介-汇率换算器的实现-插曲3
[java] 注释以及javadoc使用简介-汇率换算器的实现-插曲3
Table of Contents
1 系列文章地址
2 本文动机介绍
虽然在写代码的过程中还是会注意添加一些注释, 但是仍然没有一个规范, 因此这里针对javadoc工具中要求的注释规范进行了简单的了解, 并将它应用到"汇率换算器"实现的代码中.
3 javadoc介绍
javadoc是将java源代码中中的注释, 按照相关的规范转化为html格式的api文档的文档生成器. 在注释过程中, 可以使用html相关的标签如:
1. <em>...</em>, <strong>...</strong> 用于强调 2. <code>...</code> 用于添加代码片断 3. <img ...> 包含图片 4. <p> 空一行 5. <a href="...">...</a> 添加链接
4 注释分类–按范围分
按照范围可以将注释分类为:
- 包
- 类以及接口
- 方法
- 其他字段
5 常用的标签
@author name -> 作者 @version text -> 版本号 @since text -> 如: @since version 1.7.1 @deprecated text -> 说明该方法或类不建议使用, 如: @deprecated Use <code>setVisibile(true)</code> instead @see link -> 链接跳转到近似内容处, 通常是具体的类和方法, 如: @see com.rateexchange.Employee#raiseSalary(double)
6 针对包的注释
想要产生针对包的注释, 需要在每个包的目录下建立一个新的文件: package.html , 并且所有的注释文字都包括在<body>…</body>内.
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 <code><a href></code> or
* <code><img src></code>).
* <p/>
* e.g.: <code>string absurl = linkel.absurl("href");</code>
* <p/>
* if the attribute value is already absolute (i.e. it starts with a protocol, like
* <code>http://</code> or <code>https://</code> 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.
* <p/>
* as an alternate, you can use the {@link #attr} method with the <code>abs:</code> prefix, e.g.:
* <code>string absurl = linkel.attr("abs:href");</code>
*
* @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