JAVA_SE系列：06.文档注释和API文档

Java文档注释

            文档注释：/** 中间为文档注释 */

                      文档注释只有放在类定义之前、方法之前、Field之前、内部类之前才有效。

            javadoc命令，可以直接提取文档注释，并根据文档注释来生成API文档。

 

Java文档生成命令：javadoc -d [目录] java源文件    

                              [目录]指的是把生成的api文档放到哪个目录下。

 

/**********************************************************************

补充知识

        路径可分为：

        --绝对路径：以windows来说，以盘符开始的路径，就是绝对路径。

                    例如 g:\javanote\abc    它的路径是唯一的、确定的。

        --相对路径：以windows来说，不是以盘符开始的路径，就是相对路径。

                    例如 javanote\abc      它的路径是不确定的，想要确定

                                           需要在它前面加上基准路径。

                    假如基准路径是g:  那它的准确路径就是g:\javanote\abc

**********************************************************************/

什么叫API文档？

          API(应用程序编程接口)：编程，就是调用API的方法来控制系统。

          API文档就是API的使用说明书。

实例：

 

 

 

 

 

API文档介绍：在该页面可以通过Ctrl+F组合键调出查找菜单

 

 

文档注释程序内作用范围：

由于文档注释是用于生成API文档的，而API文档主要用于说明类、方成员变量的功能。因此javadoc工具只处理文档源文件在类、接口、方法、成员变量、构造函数和内部类之前的文档注释，忽略其他地方的文档注释。而且javadoc工具默认只处理以public或protected修饰的类、接口、方法、成员变量、构造器和内部类之前的文档注释。

 

 

 

javadoc标记

        @author：指定java程序的作者。

        @version：指定源文件的版本。

        @deprecated:不推荐使用的方法。

        @param：方法的参数说明信息。

        @return：方法的返回值说明信息。

        @see：“参见”用于指定交叉参考的内容。

        @exception：抛出异常的类型。

        @throws：抛出的异常，和@exception同义。

 

需要指出的是这些标记是有位置限制的，下面是分类

类、接口的文档注释：@see、@deprecated、@author、@version

方法、构造器的文档注释：@see、@deprecated、@param、@return、@throws、@exception

成员变量：@see、@deprecated

 

javadoc工具默认不会提取@author和@version两个标记的信息，如果需要提取这两个标记信息，应该在使用javadoc工具时指定-author和-version两个选项。