Java 文档注释

bladefury 发布于2019-08-14 15:11 / 698人阅读

摘要：概述只有种注释方式。单行注释块注释说明注释，等说明注释允许你在程序中嵌入关于程序的信息。每一个标签必须在一个新行的开始。多个相同类型的标签应该放成一组。类描述输出工具将你程序的源代码作为输入，输出一些包含你程序注释的文件。参考资料文档注释

概述

Java只有3种注释方式。

//,单行注释

/* */,块注释

说明注释，@author,@version等

说明注释允许你在程序中嵌入关于程序的信息。你可以使用javadoc工具软件来生成信息，并输出到HTML文件中。

Javadoc 标签

javadoc工具软件识别以下标签

标签	描述
@author	标示一个类的作者
@deprecated	标识一个过期的类或成员
{@docRoot}	指明当前文档跟目录的路径
@exception	指明一个类抛出的异常
@throws	和@exception一样
{@inheritDoc}	从直接父类继承的注释
{@link}	插入一个到另一个主题的链接
{@linkplain}	插入一个到另一个主题的链接，但该链接显示纯文本字体
@param	说明一个方法的参数
@return	说明返回值类型
@see	指定一个到另一个主题的链接
@serial	说明一个序列化属性
@serialData	说明通过 writeObject() 和 writeExternal() 方法写的数据
@serialField	说明一个ObjectStreamField组件
@since	标记当引入一个特定的变化时
{@value}	显示常亮的值，必须是static属性
@version	指定类的版本号

文档注释

在开始的/**之后，第一行或几行是关于类、变量和方法的主要描述。

之后，你可以包一个或多个各种各样的@标签。每一个@标签必须在一个新行的开始。

多个相同类型的标签应该放成一组。例如，如果你有三个@see标签，可以将它们一个接一个的放在一起。

</>复制代码 
/** 
* 类描述
* @author panda
* @version 1.2
*/
...

Javadoc 输出

Javadoc 工具将你Java程序的源代码作为输入，输出一些包含你程序注释的HTML文件。

每一个类的信息将在独自的HTML文件里。Javadoc也可以输出继承的树形结构和索引。

由于Javadoc的实现不同，工作也可能不同，你需要检查你的Java开发系统的版本等细节，选择合适的Javadoc版本。

</>复制代码 
实例

</>复制代码 
package com.coder4j.jse.javadoc;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
/**
 * 输入一个数，输出其平方数。
 * 
 * @author panda
 * @version 1.2
 */
public class SquareNum {
    
    /**
     * 输出平方值。
     * 
     * @param num
     *            待求平方数
     * @return 平方值
     */
    public double square(double num) {
        return num * num;
    }
    /**
     * 用户输入一个数
     * 
     * @return 返回用户输入的数
     * @exception IOException
     *                可能抛出的异常
     * @see IOException
     */
    public double getNumber() throws IOException {
        InputStreamReader isr = new InputStreamReader(System.in);
        BufferedReader inData = new BufferedReader(isr);
        String str;
        str = inData.readLine();
        return (new Double(str)).doubleValue();
    }
    /**
     * 入口主函数
     * 
     * @param args
     *            Unused.
     * @return Nothing.
     * @exception IOException
     *                On input error.
     * @see IOException
     */
    public static void main(String args[]) throws IOException {
        SquareNum ob = new SquareNum();
        double val;
        System.out.println("请输入一个数: ");
        val = ob.getNumber();
        val = ob.square(val);
        System.out.println("平方值是: " + val);
    }
}

我在eclipse里写了这个类，右键export，选择Java/javadoc 然后按提示确认，控制台输出：

</>复制代码 
正在加载程序包com.coder4j.jse.javadoc的源文件...
正在构造 Javadoc 信息...
标准 Doclet 版本 1.7.0_75
正在构建所有程序包和类的树...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/com/coder4j/jse/javadoc/SquareNum.html...
/Users/panda/Documents/lunaspace/code4j/src/com/coder4j/jse/javadoc/SquareNum.java:52: 警告 - 不能在返回类型为空的方法中使用 @return 标记。
正在生成/Users/panda/Documents/lunaspace/code4j/doc/com/coder4j/jse/javadoc/package-frame.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/com/coder4j/jse/javadoc/package-summary.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/com/coder4j/jse/javadoc/package-tree.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/constant-values.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/com/coder4j/jse/javadoc/class-use/SquareNum.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/com/coder4j/jse/javadoc/package-use.html...
正在构建所有程序包和类的索引...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/overview-tree.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/index-files/index-1.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/index-files/index-2.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/index-files/index-3.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/index-files/index-4.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/deprecated-list.html...
正在构建所有类的索引...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/allclasses-frame.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/allclasses-noframe.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/index.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/help-doc.html...
1 个警告

默认在当前项目下新增doc目录

</>复制代码 
doc/
|--com
|--index-files
|--resources
|--allclasses-frame.html
|--allclasses-noframe.html
|--constant-values.html
|--deprecated-list.html
|--help-doc.html
|--index.html
|--overview-tree.html
|--package-list
|--stylesheet.css

可以直接访问index.html,你会看到类似这样的页面。

不同的Javadoc版本可能稍有不同哟。

参考资料

Java 文档注释

云服务器 GPU云服务器文档注释 php注释文档 python注释文档文档注释c语言

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/65426.html

《Java编程思想》笔记2.一切都是对象

摘要：方法的基本组成包括名称参数返回值方法体方法名和参数列表唯一的标识出某个方法。如果返回的类型是，则的作用仅是退出方法否则必须返回正确的返回值包名名字可见性约定以域名反转作为包名，用来划分子目录，并且全部小写。点击进入我的博客 2.1用引用操纵对象尽管一切都看作对象，但操纵的标识符实际上是对象的一个引用。 String s; // s是一个String类型的引用，并没有任何对象与其...

taohonghui 2019-08-16 13:41 评论0 收藏0
java代码注释规范

摘要：下面说一下我们在诉求网二期开发中使用的代码注释规范，供大家参考下。在代码不明晰处必须有注释。在代码修改处加上修改标识的注释。在循环和逻辑分支组成的代码中加注释。代码注释是架起程序设计者与程序阅读者之间的通信桥梁，最大限度的提高团队开发合作效率。也是程序代码可维护性的重要环节之一。所以我们不是为写注释而写注释。下面说一下我们在诉求网二期开发中使用的代码注释规范，供大家参考下。原则： ...

desdik 2019-08-15 12:21 评论0 收藏0
Java核心技术笔记对象与类

摘要：核心技术卷第章对象与类面向对象程序设计创建标准类库中的类对象如何编写自己的类传统的结构化程序设计首先确定如何操作数据，再决定如何组织数据。当使用构造器时，无法改变所构造的对象类型。《Java核心技术卷Ⅰ》第4章对象与类面向对象程序设计创建标准Java类库中的类对象如何编写自己的类 OOP 传统的结构化程序设计：首先确定如何操作数据，再决定如何组织数据。面向对象程序设...

imtianx 2019-08-16 14:18 评论0 收藏0
JAVA学习之路（二）变量和常量

摘要：变量和常量中的关键字关键字对的编译器有着特殊的意义，我们在程序中应用时一定不要使用关键字来定义变量或者常量，一定要慎重哦关键字是区分大小写的哦，所以和是不一样的中的标识符标识符就是用于给程序中变量类方法等命名的符号。变量和常量 java中的关键字 showImg(https://segmentfault.com/img/bVbaF3o?w=519&h=178); 关键字对 Java ...

focusj 2019-08-19 10:55 评论0 收藏0
Java™ 教程（仔细看看“Hello World!”应用程序）

仔细看看Hello World!应用程序现在你已经看到了Hello World!应用程序(甚至可能编译并运行它)，你可能想知道它是如何工作的，这是它的代码： class HelloWorldApp { public static void main(String[] args) { System.out.println(Hello World!); // Display ...

zollero 2019-08-19 10:47 评论0 收藏0