Javadoc简单使用教程

前言

Java简介和安装

Java简介

Java是一门面向对象编程语言，不仅吸收了C++语言的各种优点，还摒弃了C++里难以理解的多继承、指针等概念，因此Java语言具有功能强大和简单易用两个特征。Java语言作为静态面向对象编程语言的代表，极好地实现了面向对象理论，允许程序员以优雅的思维方式进行复杂的编程 。

Java环境安装

Java环境安装请参考我的另一篇博客——参考链接

Javadoc

什么是Javadoc？？？

javadoc是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。
也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了。

Javadoc使用方法

最简单的例子

笔者此处的开发环境为：Java8 + Idea2019！！！

首先，我们在idea中创建一个新的java项目！！！

之后，我们会看到idea为我们生成的一个Main类

我们可以看到，这就是一个很常见的Java类，只有一个main方法，接下来我们要开始向这个类添加一些javadoc！！！

javadoc的用法非常简单，只需要在需要加注释的地方以 /** */ 的格式来编写注释， 例如：

这样子，我们就成功创建了一个javadoc， 接着我们要向javadoc中添加一些信息
在添加前， 我们需要先了解一下 javadoc 的常用标记和规范！！！

Javadoc常用标记

标签	说明	标签类型
@author 作者名	作者标识	包、类、接口
@version 版本号	版本号	包、类、接口
@date 日期	类创建日期	包、类、接口
@param 参数名 参数描述	方法的参数名及描述信息	构造方法、 方法
@return 描述	方法返回值的描述信息	方法
@deprecated 过期文本	标识随着程序版本的提升，当前API已经过期，仅为了保证兼容性依然存在，以此告之开发者不应再用这个API。	包、类、接口、值域、构造方法、 方法
@throws 异常类名	当前方法可能抛出的异常类型	构造方法、方法
@exception 异常类名	同@throws	构造方法、方法
@see 引用	查看相关类或者接口的内容，如类、方法、变量等。	包、类、接口、值域、构造函数、 方法
@since 描述文本	API在什么程序的什么版本后开发支持。	包、类、接口、值域、构造函数、 方法
{@link包.类#成员 标签}	链接到某个特定的成员对应的文档中。	包、类、接口、值域、构造函数、 方法
{@value}	当对常量进行注释时，如果想将其值包含在文档中，则通过该标签来引用常量的值。	静态值域

Javadoc规范

• 类： 每个类必须包含描述文本、@author(作者名称)、 @version(版本号) 和@date(日期)注解
• 方法：每个方法必须包含描述文本
  • 带有参数的方法：必须包含@param注解
  • 可能会抛出异常的方法： 必须包含@throws或者@exception注解
  • 带有返回值的方法： 必须包含@return 方法
  • 不再使用的方法：如果为了兼容性继续存在，则必须使用@deprecated 进行注解
• 变量：如果为成员变量则必须使用javadoc进行注解
• 常量：如果为成员常量则必须使用javadoc进行注解（常量最好修饰为静态并加上@value注解）

实际开发中javadoc的使用

我们接着来看我们刚才的例子

/**
 * 这是一个测试用的类
 * @author Cpp Primer
 * @date 2019-8-26
 * @version 1.0
 */
public class Main {
    public static void main(String[] args) throws Exception {
    }
}

可以看到，我们现在已经为刚才创建的那个类写上了javadoc注释，描述了类的用途，作者，日期和版本号!!!

看到这里，有的读者可能会有点疑惑，我们的javadoc到底有什么用呢？？？
我们现在就来看一下javadoc在实际开发中的用途

当我们的鼠标悬停在Main这个类上时，会出现一个文本框，里面描述了我们刚才在javadoc中编写的对Main类的描述。。。

想象一下，如果Main类是一个工具类，而另一个程序员在他的类中定义了Main类的对象而他不知道Main类的用途，此时我们的javadoc注释是不是起到了很大作用！！！

如果没有javadoc，我们要向其他程序员描述这个类的用途，我们需要用什么手段呢？

打电话告诉他？还是发微信qq告诉他？或者说写个文档发给他？？？

这样是不是很麻烦！！！

有了javadoc， 我们只需要在代码中插入一段注释就可以实现我们之前需要很麻烦的手段才能实现的功能！！！

如果说以上的例子还不具有说服力，那么我们接着尝试给方法添加一段javadoc！！！

/**
 * 这是一个测试用的类
 * @author Cpp Primer
 * @date 2019-8-26
 * @version 1.0
 */
public class Main {
    /**
     * 判断一个数是否为非负数
     * @param num 待判断的数
     * @return 如果为非负数则返回true, 否则返回false
     * @throws Exception 可能会抛出一个异常
     */
    public boolean testPrint(int num) throws Exception {
        if (num > 0) {
            return true;
        }
        return false;
    }
}

我们创建了一个名为testPrint的方法，用于判断一个数是否为非负数，他接受一个整型变量作为参数，将判断的结果以布尔值的方式返回。。。

假设，另一个程序员调用了我们所编写的这个方法，但是却又不知道这个方法的用途和参数的含义，这时该怎么办？？？
相信很多人都遇到过这种情况吧，在我们使用第三方库或者没有相关文档的库的时候。。。
大多数人的选择是去百度或者查阅文档，少部分人会选择编写测试方法去实验。

现在有了javadoc，就可以变得非常简单！！！
通过javadoc，我们可以轻松的查阅某个类或者方法的信息——方法的用途，参数的含义，返回值的含义等等…
在我们写自己的代码时，也可以通过javadoc让别人可以轻松的使用我们所编写的代码而不需要查阅相关的文档！！！

举个例子:
我们现在, 创建一个main方法并在main方法中调用我们刚才编写的testPrint方法，看看有什么效果？

public static void main(String[] args) throws Exception {
        Main a = new Main();
        System.out.println(a.testPrint(10));
}

是不是很方便！！！

接下来，我们再看看如何对成员变量进行javadoc注释：

/**
 * 这是一个测试用的类
 * @author Cpp Primer
 * @date 2019-8-26
 * @version 1.0
 */
public class Main {
    /**
     * 测试字段
     */
    public static final String M_TEST="test";

    /**
     * 判断一个数是否为非负数
     * @param num 待判断的数
     * @return 如果为非负数则返回true, 否则返回false
     * @throws Exception 可能会抛出一个异常
     */
    public boolean testPrint(int num) throws Exception {
        if (num > 0) {
            return true;
        }
        return false;
    }

    public static void main(String[] args) throws Exception {
    	String test2 = "test";
        Main a = new Main();
        System.out.println(a.testPrint(10));
    }
}

我特意把成员变量修饰为共有属性，为了方便我们的测试效果！！！
实际开发中，一般情况下（有一定的特殊情况这里我们就不讨论了）应该将任何成员变量声明为private属性，使用JavaBean（get、set）方法的方式进行读写值。

Javadoc总结

在java的实际开发中，编码格式规范，编码命令规范，javadoc三种相辅相成，结合起来使用!!!

养成一个好的编码习惯，就从现在开始！！！