|
@@ -1,3 +1,121 @@
|
|
|
# javascript 编写规范
|
|
|
|
|
|
+::: details 目录
|
|
|
+[[toc]]
|
|
|
+:::
|
|
|
+
|
|
|
[返回规范总览](./README.md)
|
|
|
+
|
|
|
+## 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)
|