Java面向对象系列[v1.0.0][javadoc]

编写程序时,应该说必须为程序添加一些注释,用来说明某段代码的作用,或者说明某个类的用途、某个方法的功能,以及该方法的参数和返回值的数据类型及其意义等。
添加注释主要考虑以下三个方面:

  • 永远不需要相信自己的理解力和记忆力,随着代码量的增加代码会越来越难阅读,添加注释实际上是添加编码当时的想法。
  • 可读性第一,效率第二,横向考虑整个团队的发展,个人的代码一定会有其他人阅读的,而合适的注释是个人或者其他人阅读代码成本最低的一个途径。
  • 代码即文档,其实就是说代码规范,好的代码规范下的代码可读性非常高,有一句话叫代码自解释,当代码自己能解释自己的意愿的时候可读性就有了。

代码注释分类

  • 单行注释 用双斜线 ”//” 表示
  • 多行注释 用 /------------------/ 表示
  • 文档注释 用 /**-----------------*/ 表示【用javadoc为自己的代码生成API文档用】
public class CommentTest
{
    /*
    这里面的内容全部是多行注释
    Java语言真的很有趣,
    */
    public static void main(String[] args)
    {
        // 这是一行简单的注释
        System.out.println("Hello World!");
        // System.out.println("这行代码被注释了,将不会被编译、执行!");
    }
}
  1. API文档用于说明类、方法、成员变量的功能,因此javadoc工具只处理文档源文件在类、接口、方法、成员变量、构造器和内部类之前d注释,忽略其他地方的注释,并且javadoc工具默认只处理以public或protected修饰的类、接口、方法、成员变量、构造器和内部类之前的文档注释
  2. API文档类似于产品说明书,默认只介绍暴露的供用户使用的部分。如果开发者确实想看到private修饰的内容,则在使用javadoc工具时增加-private选项即可

生成源码文件API文档

package davieyang;
/**
 * Description:
 * 网站: CSDNdavieyuang.cool
* Copyright (C), 2001-2020, davieyang.D.Y
* This program is protected by copyright laws.
* Program Name:
* Date:
* @author [email protected] * @version 5.0 */
public class JavadocTest { /** * 简单测试成员变量 */ protected String name; /** * 主方法,程序的入口 */ public static void main(String[] args) { System.out.println("Hello World!"); } }
package scc;
/**
 * Description:
 * 网站: CSDNdavieyuang.cool
* Copyright (C), 2001-2020, davieyang.D.Y
* This program is protected by copyright laws.
* Program Name:
* Date:
* @author [email protected] * @version 5.0 */
public class Test { /** * 简单测试成员变量 */ public int age; /** * Test类的测试构造器 */ public Test() { } }
package NBwang;

/**
 * Description:
 * 网站: CSDNdavieyuang.cool
* Copyright (C), 2001-2020, davieyang.D.Y
* This program is protected by copyright laws.
* Program Name:
* Date:
* @author [email protected] * @version 5.0 */
public class JavadocTagTest { /** * 一个得到打招呼字符串的方法。 * @param name 该参数指定向谁打招呼。 * @return 返回打招呼的字符串。 */ public String hello(String name) { return name + ",你好!"; } }
javadoc -d apidoc -windowtitle 测试javadoc -doctitle 学习javdoc工具测试API文档 -header 我醉欲眠卿且去 *Test.java

Java面向对象系列[v1.0.0][javadoc]_第1张图片

  • -d 指定生成API文档在本地的存储路径
  • -windowtitle: 指定一个字符串,设置API文档的浏览器窗口标题
  • -doctitle: 指定一个HTML格式的文本,用于指定概述页面标题
  • -header: 指定一个HTML格式的文本,包含每个页的页眉
  • 除此之外还可以使用javadoc -help来查看大量的javadoc选项

源码中的一些标记也会展示在API文档中:
例如@author/@version/@deprecated/@param/@return/@see/@exception/@throws等等
javadoc默认不会提取@author和@version,这两个特殊的标记需要在执行命令的时候以参数的形式指明

javadoc -d apidoc -windowtitle 测试 -doctitle 学习javadoc -header davieyang页眉 -version -author *Test.java

生成package的API文档

新建两个用英文命名的文件夹,然后将上述3段代码放在3个文件中,将其分撒在两个文件夹内,然后每个文件夹里添加对包的表述文档,该文档需要html格式,如下所示


<html>
<head>
    <meta name="author" content="davieyang.D.Y(davieyang.blog.csdn.net)" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title> davieyang包描述 title>
head>
<body>
davieyang包描述
body>
html>

<html>
<head>
    <meta name="author" content="scc.D.Y(davieyang.blog.csdn.net)" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title> scc包描述 title>
head>
<body>
scc包描述
body>
html>

然后再两个文件夹所在路径执行命令:

javadoc -d apidoc -windowtitle 测试 -doctitle 学习 javadoc工具 -header davieyang页眉 -version -author davieyang scc

你可能感兴趣的:(Java基础即高端)