Browse Source

ts 规范文档添加

haojianlong 4 years ago
parent
commit
c66bb03770
2 changed files with 185 additions and 0 deletions
  1. 118 0
      docs/guides/standard/javascript.md
  2. 67 0
      docs/guides/standard/typescript.md

+ 118 - 0
docs/guides/standard/javascript.md

@@ -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)

+ 67 - 0
docs/guides/standard/typescript.md

@@ -6,4 +6,71 @@
 
 [返回规范总览](./README.md)
 
+## 命名
+
+1. 使用<font color=red> PascalCase </font>为类型命名。
+2. 不要使用I做为接口名前缀。
+3. 使用<font color=red> PascalCase </font>为枚举值命名。
+4. 使用<font color=red> camelCase </font>为函数命名。
+5. 使用<font color=red> camelCase </font>为属性或本地变量命名。
+6. 不要为私有属性名添加_前缀。
+7. 尽可能使用完整的单词拼写命名。
+
+## 组件
+
+1. 1个文件对应一个逻辑组件 (比如:解析器,检查器)。
+2. <font color=red> .generated.*  </font>后缀的文件是自动生成的,不要手动改它。
+3. 不要导出类型/函数,除非你要在不同的组件中共享它。
+4. 不要在全局命名空间内定义类型/值。
+5. 共享的类型应该在<font color=red> types.ts </font>里定义。
+6. 在一个文件里,类型定义应该出现在顶部。
+
+## null和undefined
+
+使用``` undefined ```,不要使用``` null```。
+
+## 标记
+
+一个类型中有超过2个布尔属性时,把它变成一个标记。
+
+## 注释
+
+为函数,接口,枚举类型和类使用[JSDoc](./javascript.md)风格的注释。
+
+## 字符串
+
+1. 使用双引号""
+2. 所有要展示给用户看的信息字符串都要做好本地化工作(在<font color=red> diagnosticMessages.json </font>中创建新的实体)。
+
+## 错误提示信息
+
+1. 在句子结尾使用。
+2. 对不确定的实体使用不定冠词。
+3. 确切的实体应该使用名字(变量名,类型名等)
+4. 当创建一条新的规则时,主题应该使用单数形式(比如:An external module cannot...而不是External modules cannot)。
+5. 使用现在时态。
+6. 错误提示信息代码
+7. 提示信息被划分类成了一般的区间。如果要新加一个提示信息,在上条代码上加1做为新的代码。
+
+| 提示 | 意义 |
+| :-: | :-: |
+| 1000 | 语法信息 |
+| 2000 | 语言信息 |
+| 4000 | 声明生成信息 |
+| 5000 | 编译器选项信息 |
+| 6000 | 命令行编译器信息 |
+| 7000 | noImplicitAny信息 |
+
+## 风格
+
+1. 使用<font color=red> arrow </font>函数代替匿名函数表达式。
+2. 只要需要的时候才把arrow函数的参数括起来。
+3. 总是使用{}把循环体和条件语句括起来。
+4. 开始的{总是在同一行。
+5. 小括号里开始不要有空白。
+6. 逗号,冒号,分号后要有一个空格。
+7. 每个变量声明语句只声明一个变量
+   (比如 使用var x = 1; var y = 2;而不是var x = 1, y = 2;)。
+8. <font color=red> else </font>要在结束的}后另起一行。
+