文档化注释

  文档注释（doc comments）是用来生成参考文档的的，用来生成javadoc帮助文档，所有的文档注释以/**开始以*/作为结束，例如：

                /**
	 * 返回小于指定长度字符串
	 * 如果没有，则抛出异常
	 * */
	public Object next() {
		if(nextShort==null&&!hasNext()) throw new NoSuchElementException();
		String n = nextShort;
		nextShort = null;
		return n;
	}

 文档注释可以包含用于表示特殊种类信息的标记（tag）。所有这些标记均以@开始，如@see或@deprecated,下面逐一介绍：

1. @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
 */