文档注释(doc comments)是用来生成参考文档的的,用来生成javadoc帮助文档,所有的文档注释以/**开始以*/作为结束,例如:
/**
* 返回小于指定长度字符串
* 如果没有,则抛出异常
* */
public Object next() {
if(nextShort==null&&!hasNext()) throw new NoSuchElementException();
String n = nextShort;
nextShort = null;
return n;
}
文档注释可以包含用于表示特殊种类信息的标记(tag)。所有这些标记均以@开始,如@see或@deprecated,下面逐一介绍:
- @see标记用于产生对其他javadoc文档的交叉引用链接
例如:
/*
* @see java.lang.Object#toString()
* @see java.lang.StringBuffer
* @see java.lang.StringBuilder
* @see java.nio.charset.Charset
*/
效果:
另请参见:
Object.toString()
,
StringBuffer
,
StringBuilder
,
Charset
,
序列化表格
2. {@link}标记用于将交叉链接嵌入到文本文字中
例如:
<p>
* The class <code>String</code> includes methods for examining
* individual characters of the sequence, for comparing strings, for
* searching strings, for extracting substrings, and for creating a
* copy of a string with all characters translated to uppercase or to
* lowercase. Case mapping is based on the Unicode Standard version
* specified by the {@link java.lang.Character Character} class.
* <p>
效果:
String 类包括的方法有:检查序列的单个字符;比较字符串;搜索字符串;提取子字符串;创建字符串副本,
在该副本 中,所有的字符都被转换为大写或小写形式。大小写映射基于 Character
类指定的 Unicode Standard 版
本。
3. @param 标记用于对方法中单个参数进行文档化说明。
例如:
/* @param oldChar the old character.
* @param newChar the new character.
*/
public String replace(char oldChar, char newChar) {...}
效果:
参数:
oldChar
- 原来的字符。
newChar
- 新字符。
4. @return 对方法的返回值进行文档说明
例如:
/* @return a string derived from this string by replacing every
* occurrence of <code>oldChar</code> with
* <code>newChar</code>.
*/
public String replace(char oldChar, char newChar) {...}
效果:
返回: 一个从此字符串派生的字符串,方法是在每个出现
oldChar
的地方用
newChar
替换。
5. @throws和@exception 对异常进行文档化说明
例如:
/ * @param regex
* the regular expression to which this string is to be matched
*
* @return <tt>true</tt> if, and only if, this string matches the
* given regular expression
*
* @throws PatternSyntaxException
* if the regular expression's syntax is invalid
*
* @see java.util.regex.Pattern
*
* @since 1.4
* @spec JSR-51
*/
public boolean matches(String regex) {
return Pattern.matches(regex, this);
}
效果:
参数:
regex
- 用来匹配此字符串的正则表达式
返回: 当且仅当此字符串匹配给定的正则表达式时,才返回
true
抛出:
PatternSyntaxException
- 如果正则表达式的语法无效
6.@deprecated 表明一个标识符为过期的,已经不适合再继续使用了
例如:
/** @deprecated This method does not properly convert characters into bytes.
* As of JDK 1.1, the preferred way to do this is via the
* <code>getBytes()</code> method, which uses the platform's default
* charset.
*
* @param srcBegin index of the first character in the string
* to copy.
* @param srcEnd index after the last character in the string
* to copy.
* @param dst the destination array.
* @param dstBegin the start offset in the destination array.
* @exception IndexOutOfBoundsException if any of the following
* is true:
* /
* <li><code>dstBegin</code> is negative
* <li><code>dstBegin+(srcEnd-srcBegin)</code> is larger than
* <code>dst.length</code></ul>
*/
@Deprecated
public void getBytes(int srcBegin, int srcEnd, byte dst[], int dstBegin) {
效果:
getBytes
@Deprecated public void getBytes(int srcBegin, int srcEnd, byte[] dst, int dstBegin)
-
已过时。
该方法无法将字符正确转换为字节。从 JDK 1.1 起,完成该转换的首选方法是通过
getBytes()
构造方法,该方法使用平台的默认字符集。
7.@author 标记指定代码的作者、 @version 标记指明任意的版本规范信、@since 表明被标记实体加入系统的时间
例如:
/**@author Lee Boynton
* @author Arthur van Hoff
* @version 1.187, 07/13/04
* @see java.lang.Object#toString()
* @see java.lang.StringBuffer
* @see java.lang.StringBuilder
* @see java.nio.charset.Charset
* @since JDK1.0
*/