|
|
本文参考：
《Java面向对象编程》，作者：孙卫琴
《漫画Java编程》，作者：孙卫琴，杜聚宾
对于大型Java项目，由一个程序员单枪匹马来开发是不现实的，通常是由Java开发团队共同开发。假定大力创建的Employee类会被翠花创建的PowerApp类访问。翠花如何了解Employee类的用法呢？一种办法是翠花直接阅读大力创建的Employee类的源代码。这种办法尽管也是可行的，但比较费力。更为通用和便捷的做法是阅读Employee类的JavaDoc文档。
Java类通过JavaDoc文档来对外说明自身的用法。JavaDoc文档是基于HTML格式的帮助文档。例如图1是JDK的Java基本包中的Object类的JavaDoc文档，该文档描述了Object类以及它的各个方法的功能、用法和注意事项。在Oracle公司的官方网站上公布了JDK类库的JavaDoc文档：
https://docs.oracle.com/en/java/javase/17/
此外，在Javathinker网站的主页上也提供了最新版本的JDK类库的JavaDoc文档的链接。
图1 Object类的JavaDoc文档
JavaDoc文档是供Java程序员阅读的，程序员通过JavaDoc文档来了解其他人员开发的Java类的用法。程序员应该养成经常查阅JavaDoc文档的良好习惯。
那么，大力如何为自己创建的Employee类提供HTML格式的JavaDoc文档呢？手工编写HTML格式的JavaDoc文档显然是很费力的事。幸运的是，JDK中提供了javadoc命令，对应JDK的bin目录下的javadoc.exe程序，它能够识别Java源文件中符合特定规范的注释语句，根据这些注释语句自动生成JavaDoc文档。
能够被javadoc命令识别的注释语句需要符合以下条件：
（1）注释以“/**”开始，并以“*/”结束，里面可以包含普通文本、HTML标记和JavaDoc标记。例如以下注释将被javadoc命令解析为JavaDoc文档：/**
* 表示公司的<strong>员工</strong>
* @version 2.0
* @since 1.0
*/
public class Employee{……} |
以上注释用于描述Employee类的作用，其中<strong>为HTML标记， @version和@since为JavaDoc标记。@version标记指定Employee类的版本，@since标记指定Employee类最早是在软件项目的哪个版本出现。
javadoc命令能够解析以上注释，最后生成的JavaDoc文档如图2所示。
图2 描述Employee类的JavaDoc文档
（2）javadoc命令只处理Java源文件中在类声明、接口声明、成员方法声明、成员变量声明以及构造方法声明之前的注释，忽略位于其他地方的注释。例如在以下程序代码中，只有粗体字部分标识的注释语句会构成JavaDoc文档。变量b在method()方法中定义，是局部变量，因此在它之前的注释语句会被javadoc命令忽略。
程序猿的技术大观园：www.javathinker.net
|
|
Java技术网站 → 『 Java开发技术 』 → 『 孙卫琴姐姐的Java技术专栏 』 → 【Java基础编程专题】使用和创建JavaDoc文档
消息
查看
搜索
好友
邮件
复制
引用
IP: 已设置保密