# javascript 编写规范

::: details 目录
[[toc]]
:::


## JSDoc 注释规范

### JSDoc 注释规则

#### JSDoc注释一般应该放置在方法或函数声明之前，它必须以\/ \*\*开始，以便由<font color=red> JSDoc </font>解析器识别。其他任何以 \/\* ， \/\*\*\* 或者超过3个星号的注释，都将被JSDoc解析器忽略。如下所示：

```javascript
/*

** 一段简单的 JSDoc 注释。

*/
```
#### JSDoc 的注释效果

假如我们有一段这样的代码，没有任何注释，看起来是不是有一定的成本。
```javascript
function Book(title, author){
    this.title=title;
    this.author=author;
}

Book.prototype={
    getTitle:function(){
        return this.title;  
    },
    setPageNum:function(pageNum){
        this.pageNum=pageNum;
    }
};
```

如果使用了<font color=red> JSDoc </font>注释该代码后，代码的可阅读性就大大的提高了。
```javascript
/**
* Book类，代表一个书本.
* @constructor
* @param {string} title - 书本的标题.
* @param {string} author - 书本的作者.
*/
function Book(title, author){
    this.title=title;
    this.author=author;
}
Book.prototype={
    /**
    * 获取书本的标题
    * @returns {string|*} 返回当前的书本名称
    */
    getTitle:function(){
        return this.title;   
    },
    /**
    * 设置书本的页数
    * @param pageNum {number} 页数
    */
    setPageNum:function(pageNum){
        this.pageNum=pageNum;
    }
};
```

### @constructor 构造函数声明注释

@constructor明确一个函数是某个类的构造函数。

### @param 参数注释

我们通常会使用@param来表示函数、类的方法的参数，@param是<font color=red> JSDoc </font>中最常用的注释标签。参数标签可表示一个参数的参数名、参数类型和参数描述的注释。如下所示：

```javascript
/**
* @param {String} wording 需要说的句子
*/

function say(wording){
    console.log(wording);
}
```

### @return 返回值注释

@return表示一个函数的返回值，如果函数没有显示指定返回值可不写。如下所示：

```javascript
/**
* @return {Number} 返回值描述
*/
```

### @example 示例注释

@example通常用于表示示例代码,通常示例的代码会另起一行编写，如下所示：

```javascript
/**
* @example
* multiply(3, 2);
*/
```

### 其他常用注释

1. @overview对当前代码文件的描述。
2. @copyright代码的版权信息。
3. @author []代码的作者信息。
4. @version当前代码的版本。

### 更多参考

如果想了解更多的<font color=red> JSDoc </font>注释的内容，可参考下面的链接。 

[JSDoc 文档](https://jsdoc.app/index.html)