一、前言

使用注释对于代码的规范性、易用性、可读性及完整性等不言自明。

二、常见用法

1. 头部版本（类、接口顶部） - 标记代码出处、公司权限声明等，下面alibaba的dubbo注释样例

/*@b@ * Copyright 1999-2011 Alibaba Group.@b@ *  @b@ * Licensed under the Apache License, Version 2.0 (the "License");@b@ * you may not use this file except in compliance with the License.@b@ * You may obtain a copy of the License at@b@ *  @b@ *      http://www.apache.org/licenses/LICENSE-2.0@b@ *  @b@ * Unless required by applicable law or agreed to in writing, software@b@ * distributed under the License is distributed on an "AS IS" BASIS,@b@ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.@b@ * See the License for the specific language governing permissions and@b@ * limitations under the License.@b@ */

2. 类或接口部分 - 对类或接口详细说明，如下java并发包BlockingDeque接口样例

/**@b@ * A {@link Deque} that additionally supports blocking operations that wait@b@ * for the deque to become non-empty when retrieving an element, and wait for@b@ * space to become available in the deque when storing an element.@b@ *@b@ * <p><tt>BlockingDeque</tt> methods come in four forms, with different ways@b@ * of handling operations that cannot be satisfied immediately, but may be@b@ * satisfied at some point in the future:@b@ * one throws an exception, the second returns a special value (either@b@ * <tt>null</tt> or <tt>false</tt>, depending on the operation), the third@b@ * blocks the current thread indefinitely until the operation can succeed,@b@ * and the fourth blocks for only a given maximum time limit before giving@b@ * up.  These methods are summarized in the following table:@b@ *@b@ * <p>@b@ * <table BORDER CELLPADDING=3 CELLSPACING=1>@b@ *  <tr>@b@ *    <td ALIGN=CENTER COLSPAN = 5> <b>First Element (Head)</b></td>@b@ *  </tr>@b@ *  ...@b@ * </table>@b@ *@b@ *  ...@b@ * </table>@b@ *@b@ * <p>Memory consistency effects: As with other concurrent@b@ * collections, actions in a thread prior to placing an object into a@b@ * {@code BlockingDeque}@b@ * ...@b@ *@b@ * @since 1.6@b@ * @author Doug Lea@b@ * @param <E> the type of elements held in this collection@b@ */@b@public interface BlockingDeque<E> extends BlockingQueue<E>, Deque<E> {@b@...@b@}

预览效果

3.  对于方法描述，这边使用java安全访问控制AccessController类的本地调用的native方法的描述

/**@b@     * Performs the specified <code>PrivilegedAction</code> with privileges@b@     * enabled. The action is performed with <i>all</i> of the permissions @b@     * possessed by the caller's protection domain.@b@     *@b@     * <p> If the action's <code>run</code> method throws an (unchecked)@b@     * exception, it will propagate through this method.@b@     *@b@     * <p> This method preserves the current AccessControlContext's@b@     * DomainCombiner (which may be null) while the action is performed.@b@     *@b@     * @param action the action to be performed.@b@     *@b@     * @return the value returned by the action's <code>run</code> method.@b@     *@b@     * @exception NullPointerException if the action is <code>null</code>@b@     *@b@     * @see #doPrivileged(PrivilegedAction)@b@     * @see java.security.DomainCombiner@b@     *@b@     * @since 1.6@b@     */@b@    public static <T> T doPrivilegedWithCombiner(PrivilegedAction<T> action) {@b@       ...@b@    }

预览效果

三、语法知识

1.  @author  作者

适用范围：文件、类、方法

@author xwood.junni

2. @param  输入参数的名称  说明

适用范围：方法

@param str the String用来存放输出信息

3. @return 输出或返回参数说明

适用范围：方法

/**@b@     * Returns <tt>true</tt> if, and only if, {@link #length()} is <tt>0</tt>.@b@     *@b@     * @return <tt>true</tt> if {@link #length()} is <tt>0</tt>, otherwise@b@     * <tt>false</tt>@b@     * @since 1.6@b@     */

预览效果

4. @since JDK版本

适用范围：文件、类

@since 1.6

5. @version 版本号

适用范围：文件、类、方法

@version 1.0

6.  @see 链接目标 - 标签允许你引用其他类的文档。javadoc会在其生成的HTML文件中，用@see标签链接到其他文档

适用范围：文件、类、方法

@see #doPrivileged(PrivilegedAction)@b@@see java.security.DomainCombiner@b@@see java.text.Collator#compare(String, String)@b@@see java.lang.String#toUpperCase(Locale)

7. @throws 异常 - 标识出方法可能抛出的异常

适用范围：方法

 /* *  @b@     * @throws  IllegalFormatException@b@     *          If a format string contains an illegal syntax, a format@b@     *          specifier that is incompatible with the given arguments,@b@     *          insufficient arguments given the format string, or other@b@     *          illegal conditions.  For specification of all possible@b@     *          formatting errors, see the <a@b@     *          href="../util/Formatter.html#detail">Details</a> section of the@b@     *          formatter class specification.@b@     *@b@     * @throws  NullPointerException@b@     *          If the <tt>format</tt> is <tt>null</tt>@b@     */

预览效果

8. @deprecated 解释 - 标识对象过期

适用范围：文件、类、方法

/*   * @b@     * @deprecated This method does not properly convert bytes into characters.@b@     * As of JDK 1.1, the preferred way to do this is via the@b@     * {@code String} constructors that take a {@link@b@     * java.nio.charset.Charset}, charset name, or that use the platform's@b@     * default charset.@b@     */@b@     @Deprecated@b@    public String(byte ascii[], int hibyte, int offset, int count) {..}

预览效果

9. @link 链接地址 - 链接到一个目标，用法类似@see。但常放在注释的解释中形如{@link …}

适用范围：文件、类、方法

 {@link java.nio.charset.Charset}@b@ {@link #setBounds(int,int,int,int)}

效果参加8中java.nio.charset.Charset效果

10.  <code>、<P> 参见html标签库页面