JAVA-基本程序设计结构（转义字符、注释）

yzr-zy / 2023-08-29 / 原文

1.转义字符

**常用转义字符**
转义序列	名称	Unicode值
\b	退格	\u0008
\t	制表，实现对齐功能	\u0009
\n	换行	\u000a
\r	回车	\u000d
\f	换页	\u000c
\"	双引号	\u0022
\'	单引号	\u0027
\\	反斜线	\u005c
\s	空格。在文本中用来保留末尾空白符	\u0020
\newline	只在文本块中使用：连接这一行和下一行
——	——	——

2.注释

1. 单行注释

基本格式：//注释文字

2. 多行注释

基本格式： /* 注释文字 */

被注释的文字，不会被JVM（java虚拟机）解释执行
多行注释里面不允许有多行注释嵌套

3. 文档注释

文档注释内容可以被JDK提供的工具 javadoc 所解析，生成一套以网页形式体现的该程序的说明文档，一般写在类

PS：javadoc 可以由源文件生成一个HTML文档

0.文档格式

第一段：概要描述，通常用一句或者一段话简要描述该类的作用，以英文句号作为结束

第二段：详细描述，通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束

第三段：文档标注，用于标注作者、创建时间、参阅类等信息

1.注释的插入

javadoc 使用工具从下面几项中抽取信息

模块
包
公共类与接口
公共的和受保护的字段
公共的和受保护的构造器及方法

可以为以上各个特性编写注释。各个注释放置在所描述特性的前面。

注释以/*开始，以*/结束

/**
————————————————
*/

每个 /*.../文档注释包含标记及以后紧跟着的自由格式文本（free-form text）。标记以@开始，如@since 或 @param

自由格式文本的第一个句子应该是一个概要陈述。javadoc工具自动的将这些句子抽取出来生成概要页

在自由格式文本中，可以使用HTML修饰符

2.类注释

类注释必须放在 import 语句之后，class 定义之前

例如：

/**
* A {@code Card} object represents a playing card, such
* as "Queen of Hearts". A card has a suit (Diamond, Heart,
* Spade or Club) and a value (1 = Ace, 2 ... 10, 11 = Jack,)
*12 = Queen, 13 =King)
*/
public class Card
{
    ...
}

没有必要在每一行的开始都添加*，不添加也是合法的

大部分IDE（集成开发环境）会自动提供星号，且换行改变时，还会重新放置星号

3.方法注释

每个方法注释必须放在所描述的方法之前。

**常用Javadoc标签**
标签名	说明	标签类型
@author 作者	作者标识	包、类、接口
@version 版本号	版本号	包、类、接口
@param 参数名描述	方法的入参名及描述信息，如入参有特别要求，可在此注释。此描述可以占据多行	构造函数，方法
@return 描述	对函数返回值的注释。描述可以跨多行，可以使用HTML标记	方法
@deprecated 过期文本	标识当前API已经过期，仅为了保证兼容性依然存在，告之开发者不应再用这个API	包、类、接口、值域、构造函数、方法
@throws 异常类名	构造函数或方法所会抛出的异常	构造函数、方法
@see 引用	查看相关内容，如类、方法、变量等	包、类、接口、值域、构造函数、方法
@since 描述文本	API在什么程序的什么版本后开发支持	包、类、接口、值域、构造函数、方法
{@link 包.类#成员标签}	链接到某个特定的成员对应的文档中	包、类、接口、值域、构造函数、方法
{@value}	对常量进行注释时，如果想将其值包含在文档中，则通过该标签来引用常量的值	静态值域

@tag 格式的标签（不被{ }包围的标签）为块标签，只能在主要描述（类注释中对该类的详细说明为主要描述）后面的标签部分（如果块标签放在主要描述的前面，则生成 API 帮助文档时会检测不到主要描述）
{@tag} 格式的标签（由{ }包围的标签）为内联标签，可以放在主要描述中的任何位置或块标签的注释中

Javadoc 标签注意事项：

Javadoc 标签必须从一行的开头开始，否则将被视为普通文本。
一般具有相同名称的标签放在一起。
Javadoc 标签区分大小写，代码中对于大小写错误的标签不会发生编译错误，但是在生成 API 帮助文档时会检测不到该注释内容。

4.字段注释

只需要对公共字段（通常指的是静态常量）增加文档注释。

例如：

/**
* The " Hearts " card suit
*/
public static final int HEARTS = 1

5.通用注释

可以使用 javadoc 标签进行注释

注意：一定要使用井号（#），而不是句号（.）分隔类名与方法名（或类名与变量名）。java 编译器自身可以熟练地确定句点在分隔包、类、内部类以及方法和变量时的不同含义。但是 javadoc 工具就没有这么聪明了，因此必须对它提供帮助。

6.包注释

可以直接将类、方法和变量的注释位置放置在Java源文件中，只要用 /**...*/ 文档注释界定就可以了。但是，要想产生包注释，就需要在每一个包目录中添加一个单独的文件：

1. 提供一个名为 package-info.java 的 Java 文件。这个文件必须包含一个初始的 Javadoc 注释，以 /** 和 */ 界定，后面是一个 packge 语句。他不能包含更多的代码或注释

2. 提供一个名为 packge.html 的 HTML 文件，抽取标记 <body>...</body>之间的所有文本。

参考资料：

JAVA核心技术卷I

bilibili韩顺平：https://space.bilibili.com/651245581