API文档的阅读

时间:2022-05-24 11:14:12

API

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

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

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文档。
    • 【如下所示】

API文档的阅读

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

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

API文档的阅读

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

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

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

@return 输出参数,返回值的含义; 说明适用范围:方法
例:     * @return    <code>true</code>执行成功;
  *                 <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)