LibRec 学习笔记（六）：手把手教你如何看懂 API 帮助文档_类继承图直接子类所有已知子接口-CSDN博客

本文链接：https://blog.csdn.net/qiqi123i/article/details/104289066

对于小白来说，快速学习并且使用一个新接触的 库 | 框架 | 项目是非常有难度的，比如我们这里的 LibRec 开源库。在我们想要把它用于自己项目的时候，或多或少想要知道某个类是做什么用的，里面有什么方法以及如何去使用。那碰到这种情况，我们普遍的做法除了在搜索引擎里找寻答案，还有一种最简单且直接的方法：直接查询该库 | 框架 | 项目的 API 帮助文档。

一、API

首先解释第一个问题：什么是 API? 百度百科是这样说的：

API（Application Programming Interface，应用程序接口）是一些预先定义的函数，或指软件系统不同组成部分衔接的约定。目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问原码，或理解内部工作机制的细节。

对于这段话，我比较粗暴的理解是对方把所有的类以及方法都写好了，也就是造好了所谓的"轮子"，我们可以直接的把它放进我们的项目中，就能实现对应的功能。

二、API 帮助文档

再来解释第二个问题：什么是API帮助文档？

API 帮助文档就是对 API 中的这些函数写的文档，它可以帮助开发人员了解函数的使用方法和功能，可以极大的便利想要使用该 API 的开发人员。

在 JAVA 中，API 帮助文档体现形式为 Javadoc 文档，该文档针对整个方法或者整个类做一个简要的概述，使得别人不通过看具体的方法代码就知道某个方法或者某个类的作用和功能。

你可能会问，那 Javadoc 又是什么呢？Javadoc 是 Sun 公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的 API帮助文档，所以这也是为啥很多大的开源项目，代码注释比代码多的原因了！正是为了让使用它的人能够方便的看懂！正所谓助人也助己！

这里所谓的代码的注释是什么呢？实际上在我们使用 Java 语言进行开发的时候，当我们的鼠标悬停在某个类或者某个方法上一般就会有提示信息，而这个提示信息就是源代码上写的注释。我这里截了2张 LibRec 的源代码给大家看下：
在这里插入图片描述

则在经过源代码导出的 Javadoc 文档，也就是我们的 LibRec API 文档上我们就可以看到以上的源代码的注释已然写在 API 帮助文档上。

所以在自己写代码的时候，注意写 Javadoc 是多么重要啊，至于怎么写好这个注释，我这里不详细介绍了，有兴趣可以参考Javadoc 使用详解。

三、LibRec API

看到这里，是不是会觉得想要知道库 | 框架 | 项目的某个类或者方法如何使用，查看和源代码配套的API帮助文档是最直接有效的方法了吧！

LibRec 官方公布的 API 帮助文档链接在此，有一点要说明的是该 API 帮助文档是librec-core 2.0 版本的 API 帮助文档，而我使用的是 librec-core 3.0版本的代码，那这份代码参考上面那个API可能会有点错误，我们当然是想要使用目前最新的版本！

那如何得到最新版本的 LibRec API 呢？（如果并不在意这一点的，可以直接看下一个大标题。）读者是否记得上面描述的 :

javadoc 是 Sun 公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。

所以其实我们只有要 librec-core 3.0 版本的源代码我们就可以直接生成最新版本的LibRec API 帮助文档了！

我前面的几篇学习笔记中有提及到目前已经有 librec-core 3.0版本的 jar 包了，那是否我们可用 jar 包生成 Javadoc 文档呢？答案是不可以的！Javadoc 只能用 java 源代码生成！所以大家可以直接去 GitHub上下载最新版本的源代码，下载之后，里面的第二个文件夹就有 librec-core 3.0 的源代码。

至于自己怎么从源代码中生成最新版本的 LibRec API 帮助文档供自己使用，大家可以参考这篇链接的做法：如何使用eclipse生成javadoc帮助文档？，我这里就不重复造轮子了！

其中第5步的设置参数是：-encoding UTF-8 -charset UTF-8

四、如何看懂 LibRec API？

1、Overview 页面

在这里插入图片描述
如上图是我们刚进 LibRec API 帮助文档显示的界面，左上角显示了该库里的所有包（package），左下角显示了该库里的所有类（class），中间这部分显示的也是库里的所有包（package）。

2、Package 页面

当我们想要查看某个包的情况的时候，比如点击 net.librec.data 包，则会出现以下页面：
在这里插入图片描述
这种页面我们称之为包（package）的页面，而每一个包（package）会有单独的一页显示里面包（package）包含的所有

类（Classes）
接口（Interface）
枚举变量（Enums）
异常（Exceptions）
错误（Errors）
注释类型（Annotation Types）

的列表，以及每一个的简单介绍，所以如果想要了解这个包（package）里的任何一个内容，都可以点击进去，会有另外单独的页面显示。

3、Class | Interface 页面

比如当我们想要查看 net.librec.data 包下面的 DataContext 类，单击之后会出现以下页面
在这里插入图片描述
当我们想要查看 net.librec.data 包下面的 DataSplitter 接口，单击之后会出现以下页面

以上页面我们称之为类（CLASS）和接口（Interface）的页面，每个类, 接口, 嵌套类和嵌套接口都有各自的页面。其中每个页面都由三部分 (类/接口说明，概要表，以及详细的成员说明) 组成：

类继承图（Class inheritance diagram）
直接子类（Direct Subclasses）
所有已知子接口（All Known Subinterfaces）
所有已知实现类（All Known Implementing Classes）
类/接口声明（Class/interface declaration）
类/接口说明（Class/interface description）
嵌套类概要（Nested Class Summary）
字段概要（Field Summary）
构造器概要（Constructor Summary）
方法概要（Method Summary）
字段详细资料（Field Detail）
构造器详细资料（Constructor Detail）
方法详细资料（Method Detail）

4、Use 页面

当我们想要知道特定包 | 类 | 接口被其他哪些包、类、方法中给使用的时候，可以转至包、类或接口页面，然后单击导航栏中的 USE按钮，最后显示页面基本如下所示：
在这里插入图片描述
对于给定的类或接口 A，其 USE 页面 包含 A 的子类, 声明为 A 的字段, 返回 A 的方法, 以及带有类型为 A 的参数的方法和构造器（图中显示的只有一部分）。