API文档的阅读

系列文章目录

---

---

前言

前些天发现了一个巨牛的人工智能学习网站，通俗易懂，风趣幽默，忍不住分享一下给大家。点击跳转到网站，这篇文章男女通用，看懂了就去分享给你的码吧。

---

一、API

——Application Programming Interface(应用程序编程接口)

API是应用程序接口的意思，API是Java提供的基本编程接口，当使用Java语言进行编程时，不可能把所有的Java类、所有方法全部记下来，那么如果我们遇到一个不确定的地方时，必须通过API文档来查看某个类、某个方法的功能和用法。

二、API文档的阅读

㈠package包的用法
为什么需要package？
为了解决类之间的重名问题
为了便于管理类：合适的类位于合适的包中！
package怎么用？
通常是类的第一句非注释性语句。
包名：域名倒着写即可，再加上模块名，并与内部管理类。
注意事项：
写项目都要加包，不要使用默认包。
com.gao和com.gao.car ，这两个没有包含关系，是两个完全独立的包。只是逻辑上看起来后者是前者的一部分。
㈡JDK中主要的包
JDK所提供的所有标准Java类都存放在Java包中，如java.lang包中包含了运行Java必不可少的系统类。由于系统会自动将java.lang引入，所以不需要在源文件中用import语句来显示地引入这个包。另外，java.util和java.io是必须提供的标准包。

在JDK中常用的包有以下几种：

java.lang：语言包；
包含一些Java语言的核心类，如String、Math、Integer、System 和 Thread，提供常用的功能。
java.util：实用包；
包含一些实用工具 类，如定义系统特性、使用与日期日历相关的函数
java.awt：抽象窗口工具包；
包含了构成抽象窗口工具集（abstract window toolkits）的多个类，这些类被用来构建和管理应用程序的图形用户界面（GUI）
javax.swing：轻量级的窗口工具包，这是目前使用最广泛的GUI程序设计包；
java.io：输入输出包；
包含能提供多种输入/输出功能的类。
java.net：网络函数包；
包含执行与网络相关的操作的类。
java.applet：编制applet用到的包（目前编制applet程序时，更多的是使用swing中的JApplet类）。

三、 生成自己项目的API文档

特殊的注释
文档注释: /**
使用JAVADOC生成API文档
解决问题：代码和文档分离
如果编写Java源代码时添加了合适的文档注释，然后通过JDK提供的javadoc工具可以直接将源代码里的文档注释提取成一份系统的API文档。
【如下所示】

如上一段代码，使用了javadoc的注释形式，注释以/** 开始, 以*/ 结尾，注释写在要说明部分的前面。

如何生成javadoc呢？ 很简单，在eclipse中点击导航栏中的 project->Generate javadoc 跳出如下界面，然后勾选需要生成文档的包以及生成文档的位置就OK啦！~

截图

注：javadoc工具默认不会提取@author和@version两个标记信息，如果需要提取这两个标记应该使用javadoc工具指定的-author和－version两个版本

①常用Java注释标签（Java comment tags）
@author 作者； 适用范围：文件、类、方法
（多个作者使用多个@author标签标识，java doc中显示按输入时间顺序罗列。）
例： @author Leo. Yao

@param 输入参数的名称； 说明 适用范围：方法
例：* @param str the String用来存放输出信息。

@return 输出参数，返回值的含义； 说明适用范围：方法
例： * @return true执行成功;

•             <code>false</code>执行失败.
  

@since JDK版本用于标识编译该文件所需要的JDK环境。
适用范围：文件、类
例： * @since JDK1.6

@version 版本号用于标识注释对象的版本号
适用范围：文件、类、方法
例： * @version 1.0

@see 链接目标表示参考。会在java 文档中生成一个超链接，链接到参考的类容。
用法：
@see #field
@see #Constructor(Type, Type…)
@see #Constructor(Type id, Type id…)
@see #method(Type, Type,…)
@see #method(Type id, Type, id…)
@see Class
@see Class#field
@see Class#Constructor(Type, Type…)
@see Class#Constructor(Type id, Type id)
@see Class#method(Type, Type,…)
@see Class#method(Type id, Type id,…)
@see package.Class
@see package.Class#field
@see package.Class#Constructor(Type, Type…)
@see package.Class#Constructor(Type id, Type id)
@see package.Class#method(Type, Type,…)
@see package.Class#method(Type id, Type, id)
@see package

@throws 异常标识出方法可能抛出的异常（和exception同义）
适用范围：方法
例： * @throws IOException If an input or output exception occurred

@deprecated 解释标识对象过期
适用范围：文件、类、方法

@link 链接地址链接到一个目标，用法类似@see。但常放在注释的解释中形如{@link …}
例：
/**

• @deprecated As of JDK 1.1, replaced by

•                     {@link #setBounds(int,int,int,int)}
  

*/
②Java注释的使用顺序

• @author (指定程序的作者，classes and interfaces only, required)
• @version (源文件的版本，classes and interfaces only, required. See footnote 1)
• @param (方法的参数说明信息，methods and constructors only)
• @return (方法的返回值说明信息，methods only)
• @exception (抛出异常类型，@throws is a synonym added in Javadoc 1.2)
• @see (“参见”用于指定交叉参考的内容)
• @since
• @serial (or @serialField or @serialData)
• @deprecated (see How and When To Deprecate APIs)