day17.javaDoc文档生成

javaDoc文档生成

今天呢，我们的java基础已经学到底部了，我们回忆最开始学到注释中的文档注释，是不是给大家留了个悬念，要在javaDoc中详细讲解

那我们今天就看看什么是javaDoc，

javaDoc命令是用来生成自己API文档的

API帮助文档

javadoc是一种技术，可以将注释信息生成一个帮助文档，就是类似于java的API，

大家是不是不知道API长什么样子，那我们打开浏览器，百度搜索：jdk帮助文档，找到Oracle官网

点进去就可以看到有很多版本，我们可以选择自己的版本，当然也可以看最新的版本，这个随意，我就直接选择API8了

进去以后就可以看到非常非常多的API帮助文档，记住这个网址以后可能会经常用到，不过我们也没必要全部学会，只要学会重点的，有用的

文档大概就长这么个样子，我们以后会用到，但是今天不用，就先把他关掉

javaDoc

我们这个javadoc命令也是用来生成这个API文档的，这个就是生成一个自己的类的，跟文档注释相关的，看下来的参数，作者名，版本号，参数名等等

那我们进IDEA写一个简单的类，在base里创建一个class，名为Doc，

我们这个类就叫Doc，然后给它加个文档注释，文档注释的格式是：*/* 回车，右斜杠加两个星号加回车

按照格式先写个作者名：@author，一下就出来了，还有个下划线，再加个版本号：@version，可以叫做1.0版本，还有需要的jdk版本：@since，写上对应的版本我是jdk1.8的版本就写1.8

这是写在类上的，还可以写在方法上，比如说我们可以定义一个类变量，再写个方法，main方法大家都知道，就不用这个方法了，换一个test

public static void main(String[] args) {}
//main方法就不用了
public String test(String name){
    return name;
}

这个方法大家看不懂，但我们以后会学到，要知道这是个方法，那我们来写一下，注释，上面是给类注释的，这里是可以给方法注释的，

我们写一下注释，右斜杠加两个星号加回车，你一按下回车它就自动生成参数，

那我们在看一下更多的操作，把原来的注释删掉，然后在方法后面加上

throws Exception

然后下“杠星星”回车

可以看到他就生成了throws，说这个方法会抛出异常，这些都是可以进行一些修改的，当然你也可以在上面加上作者名之类的

这个文档，它能写的都在这个图里面，

这些不多吧，也不难，但是大家都看不懂，我们只需要写一个作者名和版本号就行了，其他的我们现在用的也比较少，万一需要用到的话，也是很简单的，

只要知道，加在类上面的是类注释，加在方法上面的是方法注释，这能理解吧

但是有人会问了，这个文档注释和普通注释也没什么区别呀，那就给你看一下它的区别，我们先找到这个文件的地址，右键该文件，选择Show in Explorer

打开文件夹以后，我们可以看到很多我们创建的java文件夹，

那我们再用命令行打开，也就是cmd，之前学过，怎么在命令行打开cmd，是不是在前面加个cmd空格就可以了

到cmd以后呢，我们要输一个命令，我们之前是不是学过java和javac的命令，

现在再教大家一个：javadoc，什么意思呢，就是java生成文档，但是，我们的java文件里面是不是有中文呀，那我们再加一条命令：-encoding UTF-8，什么意思呢，就是编码的意思，再让他的字符集也变成中文，再输入：charset UTF-8，

javadoc -encoding UTF-8 charset UTF-8

这条命令，javadoc是java命令，然后加了两个参数，这两个参数是为了能让他尽量显示中文，尽量少出现乱码的情况

那我们后面再输入文件名，是不是叫：Doc.java，

那我们直接这样去执行，看一下会不会出现问题

可以看到，它生成了一些警告，不管他们，依旧是成功输出了，

可以看到，它生成了很多html的东西，那我们去文件里看一下，

在文件里是不是多出了很多文件呐，其他的不管，我们可以找到叫：index.html的文件，这个index就是首页的意思，我们点进去看一下

进去的网页是不是跟刚才看到的API帮助文档的界面一模一样，只是很干净，只有程序包和类，那我们点进这个doc的类，进去看一下

是不是可以看到我们刚才写的一些内容，什么方法，版本，一些东西我们还没学过，都看不懂，但是，这个文档是给我们生成了，而且还非常的详细

这就是用我们的命令行，cmd，生成的这就是javadoc

---

作业：学会查找使用IDEA生成javadoc文档

今天是用命令行生成javadoc，而作业呢，是用IDEA生成，在百度上有非常多的方法，自己去搜