Skip to content

Commit

Permalink
add: 注释的高级用法：文档注释（JSDoc）
Browse files Browse the repository at this point in the history
  • Loading branch information
@qianguyihao
qianguyihao committed Oct 5, 2023
1 parent 1482ea8 commit fba2045
Showing 1 changed file with 98 additions and 55 deletions.
153 changes: 98 additions & 55 deletions 04-JavaScript基础/02-开始写JavaScript：hello world.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ JS 代码的书写位置在哪里呢？这个问题，也可以理解成：引

- 内嵌式 JS 是学习时常用的书写方式。

### 方式 3：外链式
### 方式 3：外链式（引入独立的JS文件）

```html
<!DOCTYPE html>
Expand Down Expand Up @@ -244,7 +244,7 @@ JS 代码的书写位置在哪里呢？这个问题，也可以理解成：引
// 我是注释
```

多行注释：
多行注释：（写法1）

```js
/*
Expand All @@ -253,12 +253,49 @@ JS 代码的书写位置在哪里呢？这个问题，也可以理解成：引
*/
```

补充：VS Code 中，单行注释的快捷键是「Ctrl + /」，多行注释的默认快捷键是「Alt + Shift + A」。
多行注释：（写法2）

```js
/**
* 多行注释1
* 多行注释2
*/
```

\补充：VS Code 中，单行注释的快捷键是「Ctrl + /」，多行注释的默认快捷键是「Alt + Shift + A」。

当然，如果你觉得多行注释的默认快捷键不方便，我们还可以修改默认快捷键。操作如下：

VS Code --> 首选项 --> 键盘快捷方式 --> 查找“注释”这两个字 --> 将原来的快捷键修改为其他的快捷键，比如「Ctrl + Shift + /」。

### 注释的高级用法：文档注释（JSDoc）

**JSDoc** 是 JavaScript 中用于**文档注释**的一种标准化格式。写完 JSDoc 的注释之后，再通过相关工具，开发者便可以为函数、方法、类和变量等添加注释，以便**生成可读性强的API文档**。

以下是一个基本的 JSDoc 注释示例：

```js
/**
* 这是一个示例函数，用于求两个数字的和。
* @param {number} num1 - 第一个数字
* @param {number} num2 - 第二个数字
* @returns {number} - 两个数字的和
*/
function sum(num1, num2) {
return num1 + num2;
}
```

![](https://img.smyhvae.com/202310052143987.png)

如上图所示，鼠标悬停在函数调用的地方就能看到关于这个函数的文档说明，而不需要定位函数的源码处，很神奇吧？

JSDoc经常应用于工具函数，我们甚至可以借助 JSDoc的相关工具，生成函数的一系列的API文档，部署到到网站上，方便其他开发者查阅，非常方便。这种协作方式在日常开发中极为常见。具体如何实战，各位读者可自行查阅 JSDoc 这个关键词。

另外需要说明的是，VS Code默认集成了文档注释的显示功能，可以在**单独的 JS 文件**中显示文档注释的效果，但是无法在 HTML 文件中显示效果：

![](https://img.smyhvae.com/202310052153628.png)

### 对注释的认知

很多人认为：代码注释是多余的。他们的理由是：如果注释太多，说明代码写得不清晰；而且，代码更新的同时，如果注释没更新，那段注释就成了磁盘上的垃圾，误导他人。
Expand All @@ -280,6 +317,8 @@ VS Code --> 首选项 --> 键盘快捷方式 --> 查找“注释”这两个字

## JavaScript 输出语句

在下面的这几个输出语句中， 按照使用频率来排序的话，console.log()用得最多，其次是 alert()语句；其他语句用得较少，了解即可。

### 弹窗：alert()语句

我们要学习的第一个语句，就是 alert 语句。
Expand All @@ -289,22 +328,20 @@ VS Code --> 首选项 --> 键盘快捷方式 --> 查找“注释”这两个字
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Document</title>
</head>
<body>
<script>
alert('千古壹号');
</script>
</body>
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Document</title>
</head>
<body>
<script>
alert('千古壹号');
</script>
</body>
</html>
```

**alert**（英文翻译为“警报”）的用途：**弹出“警告框”**。它会在弹窗中显示一条信息，并等待用户按下 “OK”。

`alert("")`弹窗的效果如下：
**alert**（中文翻译为“警报、警告”）的用途：**弹出“警告框”**。它会在弹窗中显示一条信息，并等待用户按下 “OK”。

![](http://img.smyhvae.com/20180116_1735.gif)

Expand All @@ -314,6 +351,48 @@ VS Code --> 首选项 --> 键盘快捷方式 --> 查找“注释”这两个字

上面的代码中，如果写了两个 alert()语句，则网页的效果是：弹出第一个警告框，点击确定后，继续弹出第二个警告框。

补充：该方法只能传入一个参数。

### 控制台输出：console.log() 打印日志

`console.log()`用于在浏览器的控制台中输出信息，里面可以传入一个或多个参数，常用于代码调试和测试。console 表示“控制台”，log 表示“输出”。括号里可以写字符串、数字、变量、表达式等。

语法格式：

```js
console.log('传入一个参数：' +arg1);
// 传入多个参数时，可以用逗号隔开
console.log('传入多个参数：', arg2, arg3);
```

控制台是程序员调试程序的地方。我们可以使用 console 语句打印日志，在控制台的 console 面板查看打印的内容，测试程序是否运行正常。

在 Chrome 浏览器中，按 F12 即可打开控制台，选择「console」栏，即可看到打印的内容。

![](http://img.smyhvae.com/20180116_2008.gif)

console 语句可以设置不同的打印等级：

```js
console.log('千古壹号1'); // 普通打印
console.warn('千古壹号2'); // 警告打印
console.error('千古壹号3'); // 错误打印
```

效果如下：

![](https://img.smyhvae.com/20211031_1552.png)

上图中，不同的打印等级，区别不大，只是颜色背景上的区别，方便肉眼区分、过滤信息。

普通人是不会在意控制台的，但是有些网站另藏玄机。比如百度首页的控制台，悄悄地放了一段招聘信息的彩蛋，挺有意思：

![](http://img.smyhvae.com/20180116_2010.png)

做前端开发时需要经常使用控制台做调试，我们甚至可以直接在控制台输入 JS 语句，然后打印执行结果，你可以自行试一试。

**总结**：alert() 主要用来显示消息给用户，console.log() 用来给程序员做调试用。

### 弹窗：confirm()语句（含确认/取消）

代码举例如下：
Expand All @@ -325,13 +404,11 @@ console.log(result);

代码运行后，页面上会显示一个弹窗。弹窗上有“确认”和“取消”两个按钮，点击“确定”返回 `true`，点击“取消”返回 `false`。

效果如下：

![20211031-1537](http://img.smyhvae.com/20211031-1537.gif)

### 弹出输入框：prompt()语句

`prompt()`就是专门弹出能够让用户输入的对话框。用得少，测试的时候偶尔会用。
`prompt()`就是专门弹出能够让用户输入内容的对话框。用得少，测试的时候偶尔会用。

JS 代码如下：

Expand All @@ -342,8 +419,6 @@ console.log(a);

上方代码中，用户输入的内容，将被传递到变量 a 里面，并在控制台打印出来。

效果如下：

![](http://img.smyhvae.com/20180116_2230.gif)

**alert()和 prompt()的区别：**
Expand All @@ -353,6 +428,8 @@ console.log(a);

### 网页内容区域输出：document.write()语句

该方法的作用是向网页中写入文本内容，可以是 HTML 代码。传入的参数可以是一个或者多个字符串。

代码举例：

```
Expand All @@ -363,40 +440,6 @@ document.write('千古前端图文教程');

![20211031_1543](http://img.smyhvae.com/20211031_1543.png)

### 控制台输出：console.log() 打印日志

`console.log()`表示在控制台中输出。console 表示“控制台”，log 表示“输出”。括号里可以写字符串、数字、变量。

控制台是程序员调试程序的地方，比如使用 console 语句打印日志，测试程序是否运行正常。

在 Chrome 浏览器中，按 F12 即可打开控制台，选择「console」栏，即可看到打印的内容。

`console.log("")`效果如下：

![](http://img.smyhvae.com/20180116_2008.gif)

console 语句可以设置不同的打印等级：

```js
console.log('千古壹号1'); //普通打印
console.warn('千古壹号2'); //警告打印
console.error('千古壹号3'); //错误打印
```

效果如下：

![20211031_1552](https://img.smyhvae.com/20211031_1552.png)

上图中，不同的打印等级，区别不大，只是颜色背景上的区别，方便肉眼区分、过滤信息。

普通人是不会在意控制台的，但是有些网站另藏玄机。比如百度首页的控制台，悄悄地放了一段招聘信息的彩蛋，挺有意思：

![](http://img.smyhvae.com/20180116_2010.png)

做前端开发时需要经常使用控制台做调试，我们甚至可以直接在控制台输入 JS 语句，然后打印执行结果。

**总结**：alert() 主要用来显示消息给用户，console.log() 用来给程序员做调试用。

## 赞赏作者

创作不易，你的赞赏和认可，是我更新的最大动力：
Expand Down

0 comments on commit fba2045

Please sign in to comment.