栏目分类:
子分类:
返回
名师互学网用户登录
快速导航关闭
当前搜索
当前分类
子分类
实用工具
热门搜索
名师互学网 > IT > 软件开发 > 后端开发 > Java

Java 学习之路 02--注释

Java 更新时间: 发布时间: IT归档 最新发布 模块sitemap 名妆网 法律咨询 聚返吧 英语巴士网 伯小乐 网商动力

Java 学习之路 02--注释

这次学习笔记的内容:

  • Java 的 3 种注释符:单行注释、多行注释、文档注释
  • javadoc工具导出文档注释
注释

注释相当于一份代码的说明文档,写注释是为了增强程序的可读性,有利于软件的维护、团队协作、软件升级和修改等等。

单行注释和多行注释

在 Java 语言中,单行注释符是 //,多行注释符是 。

public class CommentTest
{
    
    public static void main(String[] args)
    {
        // 这是一行注释
        System.out.println("Hello World!");
        // System.out.println("被注释的代码不会执行");
    }
}

添加注释也是调试程序的一个方法,把你认为可能有问题的代码注释掉,然后运行程序,如果程序正常运行,那就说明程序问题出现在注释掉的代码部分。如果程序没有正常运行,那就说明程序问题不出现在注释掉的代码部分,而是在其他代码部分。不管怎样,都能减少排查范围。

官方 API 文档

Oracle 为 Java 的基础类提供了一份 API 文档,用于描述这些类的作用和使用方法。例如 Java SE 11  API 文档的下载地址:Java Development Kit 11 Documentation

打开 docs 目录中的 index.html:

某个类的文档描述:

我们也可以为自己编写的程序添加文档注释并制作 API 文档,只要在源代码中添加合适的文档注释,然后通过 javadoc 工具将这些文档注释提取成一份系统的 API 文档。

javadoc 工具

javadoc 工具只处理文档源文件在类、接口、方法、成员变量、构造器和内部类之前的注释,忽略其他地方的注释,而且默认只处理以 public 或 protected 修饰的(因为只有 public 和 protected 才希望暴露细节)。如果要提取 private 修饰的内容,则可以在使用 javadoc 命令时添加 -private 选项。

javadoc 基本用法:javadoc 选项 Java源文件|包

常用的选项:

  • -d :指定生成的 API 文档的存放目录。
  • -windowtitle :API 文档的浏览器窗口标题。
  • -doctitle :指定一个 HTML 格式的文本,用于设置概述页面的标题。
  • -header :指定一个 HTML 格式的文本,包含每个页面的页眉。
  • -encoding :javadoc 如何用何种字符集解释文档注释的内容,例如 utf8。

只有对处于多个包下的源文件来生成 API 文档时,才有概述页面。

利用 javadoc 标记生成更详细的内容,常用的 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,如果需要,则添加 -author 和 -version 选项。

文档注释

文档注释以 结尾,每行用 * 开头,然后再写注释内容。

javadoc 使用

在当前目录下创建两份源文件,内容如下:

JavadocTest.java

package lee;

public class JavadocTest
{
    
    protected String name;
    
    public static void main(String[] args)
    {
        System.out.println("Hello World!");
    }
}

Test.java

package yeeku;

public class Test
{
    
    public int age;
    
    public Test()
    {
        
    }
}

在当前目录下打开命令行窗口,执行:

javadoc -d apidoc -windowtitle 测试 -doctitle 学习 javadoc 工具的测试 API 文档 -header 我的类  -encoding utf8 *Test.java

* 表示通配符。打开 apidoc/index.html:

 可以看到包的说明是空的,这里的内容必须由另外一个 HTML5 文件提供包注释,这个文件称为包描述文件,文件名通常为 package.html,并与该包下所有的 Java 源文件放在一起,javadoc 工具会自动寻找对应的包描述文件,并提取该包描述文件中的 元素里的内容,作为该包的描述信息。

在当前目录下创建 lee 和 yeeku 两个目录,并把 JavadocTest.java 放到 lee 目录下,Test 放到 yeeku 目录下,然后分别创建 package.html:

接着在命令行窗口执行命令:

javadoc -d apidoc -windowtitle 测试 -doctitle 学习javadoc工具的测试API文档 -header 我的类 -version -author -encoding utf8 lee yeeku

打开 apidoc/index.html:

 

转载请注明:文章转载自 www.mshxw.com
本文地址:https://www.mshxw.com/it/946384.html
我们一直用心在做
关于我们 文章归档 网站地图 联系我们

版权所有 (c)2021-2022 MSHXW.COM

ICP备案号:晋ICP备2021003244-6号