3.[Java 基础]注释,标识符与JavaDoc工具的介绍

1. 注释

1. 注释在程序中用来说明代码的作用, 类的用途, 方法的功能, 以及该方法的参数与返回值的数据类型以及意义等功能.

2. 在程序运行时, 被注释的代码不会被运行, 所以注释也常被用于程序的调试, 使用可以判断异常代码的位置或缩小异常代码的范围.

3. Java中的注释一共有三种: 单行注释, 多行注释, 文档注释.

1.1 单行注释

单行注释就是在程序中注释一行代码, 将双斜线 // 放在要注释的内容前面就可以了,

如下代码, 每一个双斜线都代表了一行单行注释.

//这是一行单行注释
public class Hello {//表示一个类的开始
  //主函数
  public static  void main(String[] args){
    System.out.println("hello world");
  }
}//表示一个类的结束

1.2 多行注释

多行注释是指一次性将多行代码注释掉, 使用 /* 开头, */ 结尾, 被这组符号包起来的中间多行代码就是被注释掉的代码.

• 多行注释里面的文字不会被 JVM 执行
• 多行注释不能嵌套多行注释

/*
这是一个多行注释
这里面的多行都是注释
*/
public class Hello {
  public static  void main(String[] args){
    System.out.println("hello world");
  }
}

1.3 文档注释

文档注释比单行注释与多行注释更为强大, 它主要用于生成 API 文档, API 文档即用与说明类, 方法, 成员变量等的功能, 因此我们可以在编写 Java 代码时添加合适的文档注释, 然后通过 JDK 提供的 Javadoc 工具可以将源码中的文档注释提取成一份 API 文档.

Javadoc 工具默认只处理 public 或 protected 修饰的类, 接口, 方法, 成员变量, 构造器和内部类之前的文档注释.

文档注释以 /** 开始, 以 */ 结尾, 中间的部分都是文档注释, 会被提取到 API 文档中

• 编写一个类测试文档注释, 并生成 Java API 文档

/**
* Description: 测试文档注释
* 网址: www.hnbian.cn
* author hnbian
* e-mail hnbian@126.com
*/
public class HelloWorld{
/**
* 定义变量 name
*/
 public String name;

 /**
  * 主函数
  *@param args 主函数的参数
  */
  public static void main(String args[]){
     System.out.println("hello world");
  }
}

#生成 Java API 文档
hnbiandeMacBook-Pro:base hnbian$ javadoc HelloWOrld.java -d helloword-doc
正在加载源文件HelloWOrld.java...
正在构造 Javadoc 信息...
正在创建目标目录: "helloword-doc/"
标准 Doclet 版本1.8.0_191
正在构建所有程序包和类的树...
正在生成helloword-doc/HelloWorld.html...
正在生成helloword-doc/package-frame.html...
正在生成helloword-doc/package-summary.html...
正在生成helloword-doc/package-tree.html...
正在生成helloword-doc/constant-values.html...
正在构建所有程序包和类的索引...
正在生成helloword-doc/overview-tree.html...
正在生成helloword-doc/index-all.html...
正在生成helloword-doc/deprecated-list.html...
正在构建所有类的索引...
正在生成helloword-doc/allclasses-frame.html...
正在生成helloword-doc/allclasses-noframe.html...
正在生成helloword-doc/index.html...
正在生成helloword-doc/help-doc.html...

1.4 文档注释常用标签

参数	说明
@author	表示程序的作者
@version	指定源文件的版本
@deprecated	废弃方法
@param	方法的参数说明信息
@return	返回值说明信息
@see	“参见”, 参考信息内容
@exception	抛出异常的类型
@throws	抛出的异常类型, 与@exceprion 相同
{@docRoot}	指明当前文档根目录的路径
{@inheritDoc}	从直接父类继承的注释
{@link}	插入到另一个主题的链接
{@linkplain}	插入到另一个主题的链接,但是该链接显示纯文本字体
@serial	说明一个序列化属性
@serialField	说明通过 writeObject() 和 writeExternal()方法写的数据
@serialField	说明一个 ObjectStreamField 组件
@since	标记当引入一个特定的变化时
{@value}	显示常量的值, 该值必须是 static 属性
@version	指定类的版本

2. Javadoc 工具介绍

javadoc 可以对源文件, 包生成 API 文档, 参数列表如下:

参数	说明
@<file>	从文件读取选项和文件名
-bootclasspath <路径>	覆盖用于非模块化发行版的平台类文件的位置
-breakiterator	计算带有 BreakIterator 的第一个语句
-doclet <类>	通过替代 doclet 生成输出
-docletpath <路径>	指定查找 doclet 类文件的位置
–enable-preview	启用预览语言功能。与-source 或–release一起使用。
-encoding <名称>	源文件编码名称
-exclude <程序包列表>	指定要排除的程序包列表
-extdirs <目录列表>	覆盖所安装扩展的位置
-locale <名称>	要使用的区域设置, 例如, en_US 或 en_US_WIN
–module <模块>(, <模块>)*	文档化指定模块
-package	显示程序包/protected/public类型和成员。对于命名模块, 显示所有程序包和所有模块详细信息。
-private	显示所有类型和成员。对于命名模块, 显示所有程序包和所有模块详细信息。
-protected	显示protected/public类型和成员(默认设置)。对于命名模块, 显示导出的程序包和模块的 API。
-public	只显示public类型和成员。对于命名模块, 显示导出的程序包和模块的 API。
-quiet	不显示状态消息
–release <发行版>	提供与指定发行版的源兼容性
–system <jdk>	覆盖用于模块化发行版的系统模块的位置
–version	输出版本信息
-Werror	如果出现任何警告，将报告错误
–add-stylesheet <file>	用于所生成文档的其他样式表文件
–allow-script-in-comments	允许在选项和注释中使用 JavaScript
-author	包含@author 段
-bottom <html-code>	包含每个页面的底部文本
-charset <charset>	用于跨平台查看生成的文档的字符集
-d <directory>	输出文件的目标目录
-docencoding <name>	指定输出的字符编码
-docfilessubdirs	递归复制文档文件子目录
-doctitle <html-code>	包含概览页面的标题
-footer <html-code>	包含每个页面的页脚文本
-header <html-code>	包含每个页面的页眉文本
-helpfile <file>	包含帮助链接所链接到的文件
-html5	生成 HTML 5 输出。此选项不再是必需的。
–javafx, -javafx	启用 JavaFX 功能
-keywords	随程序包, 类和成员信息一起附带 HTML 元标记
-linksource	以 HTML 格式生成源文件
-nocomment	不生成说明和标记, 只生成声明
-nodeprecated	不包含@deprecated 信息
-nodeprecatedlist	不生成已过时的列表
-nohelp	不生成帮助链接
-noindex	不生成索引
-nonavbar	不生成导航栏
–no-platform-links	不生成指向平台文档的链接
-nosince	不包括@since 信息
-notimestamp	不包括隐藏的时间戳
-notree	不生成类分层结构
–override-methods (detail|summary)	在详细资料部分或概要部分中的文档覆盖方法
-overview <file>	从 HTML 文件读取概览文档
-serialwarn	生成有关@serial 标记的警告
-splitindex	将索引分为每个字母对应一个文件
-taglet	要注册的 Taglet 的全限定名称
-tagletpath	Taglet 的路径
-top <html-code>	包含每个页面的顶部文本
-use	创建类和程序包用法页面
-version	包含@version 段
-windowtitle <text>	文档的浏览器窗口标题

3. Java API 文档的下载与使用

3.1 下载 JavaAPI 文档

Oracle 为 Java 基础类提供了相应的 API 文档, 告诉开发者如何使这些类, 下载 API 的方法很简单, 登录 https://www.oracle.com/java/technologies/javase-jdk17-doc-downloads.html 网址, 即可下载到 Java17 的 API 文档.

点击下载之后就会得到一个jdk-17.0.1_doc-all.zip压缩文件, 将文件解压后, 进入文档目录可以看到如下结构的文档.

3.2 Java API 页面介绍

1. 首页

打开 index.html 就会进入到JAVA17 API 文档首页.

Java API 首页是一个概述页面介绍了 Java 的全部模块, 与各种不同查看API的方式

Java API 将模块分为三类:

模块	说明
Java SE	主要包含了 Java SE 的各种类.
JDK	包含了 JDK 的各种工具类, 这部分 API 在不同 JDK 上可能存在差异.
Other Modules	其他模块, 包含其他功能的 API.

2. 类信息页

4. 分隔符

Java 语言中的分隔符有 分号 ; , 花括号{}, 方括号[], 圆括号(), 空格, 圆点.

4.1 分号 ;

• 分号是 Java 语言中语句的分隔符, 因此每个 Java 语句都需要以分号 ; 结尾

• Java 也允许同一行写多条语句, 语句之间使用分号隔开即可

• 一条语句也可以分为很多行, 只需要在最后一行结尾的地方使用分号

4.2 花括号{}

• 花括号的作用是定义一个代码块, 一个代码块就是指 { 和 } 之间包含的一段代码, 该代码块在逻辑上是一个整体。
• 在 Java 语言中, 类定义的部分必须放在同一个代码块中, 定义方法的方法体必须要放在代码块中, 此外条件语句中的条件执行体和循环语句中的循环体通常也放在代码块里 .

4.3 方括号[]

方括号的主要作用是访问数组元素, 方括号通常紧跟在数组变量名后面, 方括号里面是存放着要访问的数组中的某个元素的下标索引。

4.4 圆括号()

圆括号主要有一下几个功能 :

• 定义方法时必须将所有形参放到圆括号中
• 调用方法时需要将所有实参放进圆括号内
• 圆括号还可以将表达式中的某个部分括成一个整体
• 圆括号还可以作为强制类型转换的符号

4.5 空格

• Java 语言中的空格符号包括: 空格符 ( space ) , 制表符 ( Tab ) , 回车 ( Enter )

• 空格符号可以出现在 Java 语言的任何位置, 但不要使用空格符号将变量名分隔开

• 空格符号出现的数量也可以是任意多个

• Java 源程序会使用空格键进行合理的缩进, 使 Java 程序可读性更好

4.6 圆点.

圆点通常作为类或对象和它的成员之间的分隔符, 表名调用某个类或某个实例指定的成员

5. 标识符

Java 对各种变量, 方法和类等命名时使用的字符序列称为标识符

凡是可以自己起名字的地方都是标识符, 如：

int num = 90; 
// 其中 num 即为标识符

5.1 标识符的命名规则

标识符的命名, 需要注意以下规则:

1. 标识符可以由26 个英文字母, 数字 0~9, 下划线 _ ,美元 $ 符号组成, 但是不能以数字开头
2. 标识符不能是 Java 关键字和保留字, 但关键字和保留字可以作为标识符的一部分
3. 标识符只能包含美元符号 $ 不能包含 @,# 等特殊符号.
4. 标识符不能包含空格
5. Java中严格区字母分大小写
6. 标识符长度无限制, 但是一般不建议使用过长的标识符
7. 从Java9 开始, 不允许使用单独的下划线 _ 作为标识符, 下划线必须与其他字符组合在一起才能作为标识符

public class Identifier {
    public static void main(String[] args) {
        // 变量名中可以包含关键字
        int abclass = 10;

        // Java 中 区分大小写, a 跟 A 不是同一个变量
        int a = 20;
        int A = 30;
        System.out.println("a = " + a );
        System.out.println("A = " + A );

        // 变量不能以数字开头
        //int 1ab = 40;

        // 关键字不能作为变量名
        //int class = 50;
    }
}

5.2 标识符的命名规范

模块	说明
包名	多个单词组成时, 所有字母都小写, 比如, com.hnbian.service
类名	当类名由多个单词组成时, 所有单词首字母都大写, 如 DateUtil
接口名	当接口名由多个单词组成时, 所有单词首字母都大写, 如 UserService
方法名	当方法名有多个单词组成时, 第一个单词首字母小写, 其余单词首字母均大写, 如 getUserName
常量名	常量名的所有字母都要大写, 并且当常量名由多个单词组成时, 单词之间用下划线分隔, 如 MYSQL_URL
变量名	当变量名有多个单词组成时, 第一个单词首字母小写, 其余单词首字母均大写, 如 userName

6. 从键盘获取数据代码示例

在编程中需要接收用户输入的数据, 就可以使用键盘输入语句来获取, 获取键盘输入需要一个扫描器对象, 就是 Scanner.

import java.util.Scanner;

public class ScannerTest {
    public static void main(String[] args) {
        // 创建 scanner 对象,  new 会创建一个新的对象
        Scanner scanner = new Scanner(System.in);
        // 接收命令行输入的数据, 当程序执行到此行时会等待用户输入
        String name = scanner.next();
        int age = scanner.nextInt();
        double salary = scanner.nextDouble();
        System.out.println("name = "+name +" age = "+ age +" salary = "+ salary);
    }
}