用户工具

站点工具


代码规范:javadoc标记

差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

代码规范:javadoc标记 [2016/04/19 18:04] (当前版本)
neohope 创建
行 1: 行 1:
 +====== JavaDoc标记 ======
 +JavaDoc标记是插入文档注释中的特殊标记。JavaDoc 标记由“@”、标记、专用注释引用组成。
 +
 +关于JavaDoc标记使用的详细信息请参考下面链接:
 +http://​java.sun.com/​j2se/​1.4.1/​docs/​tooldocs/​windows/​javadoc.html#​javadoctags
 +
 +===== JavaDoc主要标记 =====
 +<sxh java; >
 +    /*
 +    * @author ​      ​(用于类和接口,标明开发该类模块或接口的作者)
 +    * @version ​     (用于类和接口,标明该模块的版本)
 +    * @param ​       (用于方法和构造函数,说明方法中的某个参数)
 +    * @return ​      ​(用于方法,说明方法的返回值)
 +    * @exception ​   (用于方法,说明方法可能抛出的异常,​同@throws)
 +    * @see          (对类、属性、方法的说明,参考转向,也就是相关主题)
 +    * @since ​       (说明引进该类、方法或属性的起始版本)
 +    * @deprecated ​  ​(说明某类或方法不被推荐使用,以及相应的替代类或替代方法)
 +    * */
 +</​sxh>​
 +
 +===== @author和@version =====
 +    @author标记用于指明类或接口的作者。在缺省情况下JavaDoc工具将其忽略,但命令行开关-author可以修改这项功能,使其包含的信息被输出。
 +    句法:@author作者名。 ​  
 +    @author可以多次使用,以指明多个作者,生成的文档中每个作者之间使用逗号“,”分隔。
 +
 +    @version标记用于指明类或接口的版本。
 +    句法:@version 版本号。
 +例:
 +<sxh java; >
 +    /**
 +     * @author dengwuping
 +     ​* ​
 +     * @version Version 1.00
 +     */
 +</​sxh>​
 +
 +===== @param、@return和@exception =====
 +这三个标记都是用于方法说明。
 +    @param标记用于描述方法的参数。
 +    句法:@param参数名 参数的描述。
 +    每一个@param只能描述方法的一个参数,所以,如果方法需要多个参数,就需要多次使用@param来描述。
 +    ​
 +    @return标记用于描述方法的返回值。
 +    句法:@return返回值描述。
 +    一个方法中只能用一个@return。 ​
 +    ​
 +    @exception标记用于说明方法可能抛出的异常,同@throws。
 +    句法:@exception 异常类 抛出异常的原因。
 +    一个方法可以有多个@exception标记。
 +例:
 +<sxh java; >
 +    /**
 +     * @param ​ param1 ​ description of param1
 +     * @param ​ param2 ​ description of param2
 +     * @return ​ true or false
 +     * @exception ​ java.lang.Exception ​ throw when switch is 1
 +     * @exception ​ NullPointerException ​ throw when parameter is null
 +     */
 +</​sxh>​
 +
 +===== @see =====
 +该标记用于参考转向。
 +    句法:
 +    @see 类名
 +    @see #​方法名或属性名
 +    @see 类名#​方法名或属性名
 +    @see <a href=”HTML链接”>​HTML链接字</​a>​
 +    关于类名,如果JAVA源文件中的import语句包含了该类,可以只写出类名;若没有包含,则需要写出类全名(如java.lang.String)。对于方法或属性,如果没有指定类名,则默认为当前类。对于方法,还需要写出方法名及其参数类型,没有参数的,需要写一对括号。
 +例:
 +<sxh java; >
 +    /**
 +     * @see String
 +     * @see java.lang.String The String Class
 +     * @see java.lang.StringBuffer#​str
 +     * @see #str
 +     * @see #str()
 +     * @see #​main(String[])
 +     * @see Object#​toString()
 +     * @see <a href=”http://​…/​somepage.html”>​some page</​a>​
 +     */
 +</​sxh>​
 +
 +===== @since =====
 +该标记用于说明引进某个类、方法或属性的起始版本。
 +    句法:@since版本号
 +    其中,对“版本号”没有特殊的格式要求。@since标记可用于包、类、接口、方法、属性的文档注释里。表示它描述的修改或特性从“版本号”所描述的版本开始就存在了。
 +例:
 +<sxh java; >
 +    /**
 +     * @since 1.2
 +     */
 +</​sxh>​
 +
 +===== @deprecated =====
 +该标记用于指出某个类或方法不被推荐使用,以及相应的替代类或替代方法。
 +
 +    句法:@deprecated ​ deprecate-Description
 +    @deprecated标记可用于包、类、接口、方法、属性的文档注释里。Deprecate-Description里,首先要说明该类或者方法从什么时候(什么版本)起不再使用,其次要说明用哪个类或者方法可以替代它。可以使用@see或@link指明替代类或替代方法。
 +
 +例:
 +<sxh java; >
 +    /**
 +     * @deprecated ​ As of JDK 1.1, replaced by {@link setPrice(int)}
 +     */
 +</​sxh>​
 +
 +又例:
 +<sxh java; >
 +    /**
 +     * @deprecated ​ As of JDK 1.1, replaced by setBounds
 +     * @see #​setBounds(int,​ int, int, int)
 +    */
 +</​sxh>​
  
代码规范/javadoc标记.txt · 最后更改: 2016/04/19 18:04 由 neohope