>>分享孙卫琴的Java技术专稿和著作 书籍支持  卫琴直播  品书摘要  在线测试  资源下载  联系我们
发表一个新主题 开启一个新投票 回复文章 您是本文章第 13647 个阅读者 刷新本主题
 * 贴子主题:  【Java基础编程专题】使用和创建JavaDoc文档 回复文章 点赞(0)  收藏  
作者:sunweiqin    发表时间:2022-03-15 19:17:24     消息  查看  搜索  好友  邮件  复制  引用

本文参考:
《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文档的链接。
点击在新窗口中浏览原图
CTRL+鼠标滚轮放大或缩小
图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所示。
点击在新窗口中浏览原图
CTRL+鼠标滚轮放大或缩小
图2  描述Employee类的JavaDoc文档
(2)javadoc命令只处理Java源文件中在类声明、接口声明、成员方法声明、成员变量声明以及构造方法声明之前的注释,忽略位于其他地方的注释。例如在以下程序代码中,只有粗体字部分标识的注释语句会构成JavaDoc文档。变量b在method()方法中定义,是局部变量,因此在它之前的注释语句会被javadoc命令忽略。




程序猿的技术大观园:www.javathinker.net
  Java面向对象编程-->Java注解
  JavaWeb开发-->访问数据库(Ⅱ)
  JSP与Hibernate开发-->映射对象标识符
  Java网络编程-->RMI框架
  精通Spring-->Vue CLI脚手架工具
  Vue3开发-->Vue Router路由管理器
  【Vue.js技术专题】路由管理器的基本用法
  【Spring Cloud Alibaba专题】ShardingSphere核心概念
  【Spring Cloud Alibaba专题】Nacos集群的Raft算法
  【持久化专题】为什么JPA和Hibernate的持久化方法都抛出运行...
  【Spring专题】用Spring框架进行文件下载
  【持久化专题】用orphanRemoval属性映射父子关系
  【持久化专题】用@Formula注解映射派生属性
  【持久化专题】@Access注解设定Hibernate访问类的属性的方式
  【持久化专题】通过JPA API调用存储过程
  【Java网络编程专题】用Apache FTPClient在FTP服务器上创建目...
  【Java网络编程专题】创建基于SSL的安全服务器和安全客户的范...
  【Java网络编程专题】异步通道和异步运算结果
  【Java网络编程专题】通过JDBC API调用存储过程
  【JavaWeb专题】Tomcat与IIS集成详解
  【Java基础编程专题】Java集合的批量操作
  更多...
 IPIP: 已设置保密
楼主      
1页 0条记录 当前第1
发表一个新主题 开启一个新投票 回复文章


中文版权所有: JavaThinker技术网站 Copyright 2016-2026 沪ICP备16029593号-2
荟萃Java程序员智慧的结晶,分享交流Java前沿技术。  联系我们
如有技术文章涉及侵权,请与本站管理员联系。