一、前言
使用注释对于代码的规范性、易用性、可读性及完整性等不言自明。
二、常见用法
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标签库页面