|
@@ -0,0 +1,403 @@
|
|
|
+---
|
|
|
+sidebarDepth: 2
|
|
|
+---
|
|
|
+
|
|
|
+# TypeScript 文档注释规范
|
|
|
+::: details 目录
|
|
|
+[[toc]]
|
|
|
+:::
|
|
|
+
|
|
|
+## 介绍
|
|
|
+Typedoc 是一个 TypeScript 语言的文档生成工具。可以根据我们写的 TypeScript 代码,直接生成 API 帮助文档。
|
|
|
+
|
|
|
+参考地址:[https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDJGIJB](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDJGIJB)
|
|
|
+
|
|
|
+## 安装
|
|
|
+可安装有全局安装与配置 package.json 文件两种方式。
|
|
|
+
|
|
|
+### 全局安装
|
|
|
+```shell
|
|
|
+D:\Project\ts> npm install --global typedoc
|
|
|
+```
|
|
|
+
|
|
|
+### package.json
|
|
|
+配置项目的 package.json, 增加 typedoc 的依赖。
|
|
|
+```json{5}
|
|
|
+{
|
|
|
+ ......
|
|
|
+ "devDependencies": {
|
|
|
+ ......
|
|
|
+ "typedoc": "^0.17.7",
|
|
|
+ ......
|
|
|
+ },
|
|
|
+ ......
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+在项目文件夹执行如下命令安装 typedoc。
|
|
|
+
|
|
|
+```shell
|
|
|
+D:\Project\ts> npm install
|
|
|
+```
|
|
|
+
|
|
|
+## 使用
|
|
|
+
|
|
|
+```shell
|
|
|
+D:\Project\ts> typedoc --out docs src
|
|
|
+```
|
|
|
+
|
|
|
+### typedoc 参数
|
|
|
+| 参数 | 类型 | 说明 |
|
|
|
+|:---:|:---:|-----|
|
|
|
+| out | string | 输出目录 |
|
|
|
+| module | string | 模块引入方式,可以是 commonjs, amd, system, umd |
|
|
|
+| target | string | ES3(默认), ES5, ES6 |
|
|
|
+| name | string | 项目标题 |
|
|
|
+| theme | string | 皮肤可以是 default or minimal or 一个路径 |
|
|
|
+| readme | string | readme 文件,markdown 文件的相对地址 |
|
|
|
+| includeDeclarations | boolean | 是否包含 .d.ts 文件,如果你的项目是 javascript 写的,可以使用声明文件的方式来支持 TypeScript 并生成文档 |
|
|
|
+| excludeExternals | boolean | 是否排除外部引入的模块 |
|
|
|
+| excludePrivate | boolean | 是否排除 private 修饰的相关字段方法 |
|
|
|
+| excludeProtected | boolean | 是否排除 protected 修饰的相关字段方法 |
|
|
|
+| hideGenerator | boolean | 隐藏页底的全局链接 |
|
|
|
+| version | boolean | 显示 typedoc 版本 |
|
|
|
+| help | boolean | 显示帮助信息 |
|
|
|
+| gaID | string | 如果有 Google Analytics 的跟踪ID,可以设置 |
|
|
|
+| exclude | string | 排除文件 |
|
|
|
+| includes | string | 包含文件,应该是一个文件夹的名字,会将下面所有的md文件包含进来(需要使用 [[include:document.md]] 引入) |
|
|
|
+| media | string | 包含媒体,应该是一个文件夹的名字,会包含文件夹下的图片等各种媒体文件(需要使用 !\[logo](media://logo.png) 引入) |
|
|
|
+
|
|
|
+## 标签
|
|
|
+| 标签 | 说明 | 备注 |
|
|
|
+|:-------------:|---------|----------|
|
|
|
+| @author | 作者 | 用于类和接口注释。可有零到多个。 |
|
|
|
+| @deprecated | 废除标志 | 标识过期API(为了保证兼容性,仍可用,但不推荐用)。最多一个。 |
|
|
|
+| @exception<br>@throws | 异常描述 | 构造函数与函数注释使用,指示函数会抛出异常。可有零到多个。 |
|
|
|
+| @param | 方法的参数 | 仅供类、接口、方法注释时使用。同一个注释块可同时出现多个param描述。 |
|
|
|
+| @return | 返回描述 | 仅供函数注释时使用。除 void 方法外其它所有方法必须有一个 return 描述。 |
|
|
|
+| @see | 参考描述 | 引用,查看相关的内容,如类,方法,变量等。可有零到多个。 |
|
|
|
+| @serial<br>@serialField<br>@serialData | 序列化描述 | 可有多个。 |
|
|
|
+| @since | 起始版本 | 只有一个。 |
|
|
|
+| @version | 版本号 | 用于类和接口注释。零或一个。 |
|
|
|
+
|
|
|
+### @author
|
|
|
+----
|
|
|
+
|
|
|
+可以有多个作者。
|
|
|
+
|
|
|
+**语法:**
|
|
|
+```
|
|
|
+@author name-text
|
|
|
+```
|
|
|
+
|
|
|
+**参数:**
|
|
|
+
|
|
|
+* *name-text*
|
|
|
+
|
|
|
+   作者。
|
|
|
+
|
|
|
+**示例:**
|
|
|
+
|
|
|
+一个作者
|
|
|
+```typescript {4}
|
|
|
+/**
|
|
|
+ * 点数据类型定义
|
|
|
+ *
|
|
|
+ * @author 庞利祥 <sybotan@126.com>
|
|
|
+ */
|
|
|
+export class SPoint {
|
|
|
+ //
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+多个作者
|
|
|
+```typescript {4,5}
|
|
|
+/**
|
|
|
+ * 点数据类型定义
|
|
|
+ *
|
|
|
+ * @author 庞利祥 <sybotan@126.com>
|
|
|
+ * @author 庞凌峰 <sandy@126.com>
|
|
|
+ */
|
|
|
+export class SPoint {
|
|
|
+ //
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### @deprecated
|
|
|
+----
|
|
|
+废除标志
|
|
|
+
|
|
|
+**语法:**
|
|
|
+```
|
|
|
+@deprecated deprecated-text
|
|
|
+```
|
|
|
+
|
|
|
+**参数:**
|
|
|
+* *deprecated-text*
|
|
|
+
|
|
|
+   废除的原因。
|
|
|
+
|
|
|
+**示例:**
|
|
|
+```typescript{5,14}
|
|
|
+/**
|
|
|
+ * 点数据类型定义
|
|
|
+ *
|
|
|
+ * @author 庞利祥 <sybotan@126.com>
|
|
|
+ * @deprecated 使用 SPoint 类代替。
|
|
|
+ */
|
|
|
+export class SPointF {
|
|
|
+
|
|
|
+ /**
|
|
|
+ * 平移点
|
|
|
+ *
|
|
|
+ * @param dx X 轴位移
|
|
|
+ * @param dy Y 轴位移
|
|
|
+ * @deprecated 不在支持
|
|
|
+ */
|
|
|
+ translate(dx: number, dy: number): void {
|
|
|
+ this.x += dx;
|
|
|
+ this.y += dy;
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### @exception 或 @throws
|
|
|
+----
|
|
|
+
|
|
|
+标识函数会抛出异常。
|
|
|
+
|
|
|
+**语法:**
|
|
|
+```
|
|
|
+@exception class-name description
|
|
|
+```
|
|
|
+或
|
|
|
+```
|
|
|
+@throws class-name description
|
|
|
+```
|
|
|
+
|
|
|
+
|
|
|
+**参数:**
|
|
|
+
|
|
|
+* *class-name*
|
|
|
+
|
|
|
+   抛出的异常类。
|
|
|
+
|
|
|
+* *description*
|
|
|
+
|
|
|
+   异常描述。
|
|
|
+
|
|
|
+**示例:**
|
|
|
+```typescript
|
|
|
+
|
|
|
+```
|
|
|
+
|
|
|
+
|
|
|
+### @param
|
|
|
+----
|
|
|
+函数入参。
|
|
|
+
|
|
|
+**语法:**
|
|
|
+```
|
|
|
+@param parameter-name description
|
|
|
+```
|
|
|
+
|
|
|
+**参数:**
|
|
|
+
|
|
|
+* *parameter-name*
|
|
|
+
|
|
|
+   参数名。
|
|
|
+
|
|
|
+* *description*
|
|
|
+
|
|
|
+   参数描述。
|
|
|
+
|
|
|
+**示例:**
|
|
|
+
|
|
|
+函数入参
|
|
|
+
|
|
|
+```typescript {5,6}
|
|
|
+export class S {
|
|
|
+ /**
|
|
|
+ * 平移矩形
|
|
|
+ *
|
|
|
+ * @param dx x 轴位移
|
|
|
+ * @param dy y 轴位移
|
|
|
+ */
|
|
|
+ translate(dx: number, dy: number): void {
|
|
|
+ this.x += dx;
|
|
|
+ this.y += dy;
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+构造函数入参
|
|
|
+
|
|
|
+```typescript {5-8}
|
|
|
+export class SRect {
|
|
|
+ /**
|
|
|
+ * 构造函数
|
|
|
+ *
|
|
|
+ * @param x x 轴坐标
|
|
|
+ * @param y y 轴坐标
|
|
|
+ * @param width 宽度
|
|
|
+ * @param height 高度
|
|
|
+ */
|
|
|
+ constructor(x: number, y: number, width: number, height: number) {
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+带泛型的函数
|
|
|
+```typescript {4,5}
|
|
|
+/**
|
|
|
+ * 返回对象的标识符
|
|
|
+ *
|
|
|
+ * @param <T> 泛型类型
|
|
|
+ * @param arg 入参
|
|
|
+ */
|
|
|
+function identity<T>(arg: T): T {
|
|
|
+ return arg;
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### @return
|
|
|
+----
|
|
|
+函数返回值描述。
|
|
|
+
|
|
|
+**语法:**
|
|
|
+```
|
|
|
+@return description
|
|
|
+```
|
|
|
+
|
|
|
+**参数:**
|
|
|
+
|
|
|
+* *description*
|
|
|
+
|
|
|
+   返回值描述。
|
|
|
+
|
|
|
+**示例:**
|
|
|
+```typescript{5}
|
|
|
+/**
|
|
|
+ * 旋转变形
|
|
|
+ *
|
|
|
+ * @param angle 绕 z 轴旋转角度(单位角度)
|
|
|
+ * @return 返回自身
|
|
|
+ */
|
|
|
+rotate(angle: number): SMatrix {
|
|
|
+ ......
|
|
|
+ return matirx;
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### @see
|
|
|
+----
|
|
|
+
|
|
|
+**语法:**
|
|
|
+```
|
|
|
+@see reference
|
|
|
+```
|
|
|
+
|
|
|
+**参数:**
|
|
|
+
|
|
|
+* *reference*
|
|
|
+
|
|
|
+   参考对象。
|
|
|
+
|
|
|
+**示例:**
|
|
|
+```typescript
|
|
|
+
|
|
|
+```
|
|
|
+
|
|
|
+### @serial 或 @serialField 或 @serialData
|
|
|
+----
|
|
|
+
|
|
|
+**语法:**
|
|
|
+```
|
|
|
+@serial field-description | include | exclude
|
|
|
+```
|
|
|
+
|
|
|
+**参数:**
|
|
|
+
|
|
|
+**示例:**
|
|
|
+```typescript
|
|
|
+
|
|
|
+```
|
|
|
+
|
|
|
+### @serialField
|
|
|
+----
|
|
|
+
|
|
|
+**语法:**
|
|
|
+```
|
|
|
+@serialField field-name field-type field-description
|
|
|
+```
|
|
|
+
|
|
|
+**参数:**
|
|
|
+
|
|
|
+**示例:**
|
|
|
+```typescript
|
|
|
+
|
|
|
+```
|
|
|
+
|
|
|
+### @serialData
|
|
|
+----
|
|
|
+
|
|
|
+**语法:**
|
|
|
+```
|
|
|
+@serialData data-description
|
|
|
+```
|
|
|
+
|
|
|
+**参数:**
|
|
|
+
|
|
|
+**示例:**
|
|
|
+```typescript
|
|
|
+
|
|
|
+```
|
|
|
+
|
|
|
+### @since
|
|
|
+----
|
|
|
+
|
|
|
+**语法:**
|
|
|
+```
|
|
|
+@since since-text
|
|
|
+```
|
|
|
+
|
|
|
+**参数:**
|
|
|
+
|
|
|
+* *since-text*
|
|
|
+
|
|
|
+   起始版本。
|
|
|
+
|
|
|
+**示例:**
|
|
|
+```typescript
|
|
|
+/**
|
|
|
+ * @since 1.0.0
|
|
|
+ */
|
|
|
+export class SObject {
|
|
|
+ //
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### @version
|
|
|
+----
|
|
|
+版本号。
|
|
|
+
|
|
|
+**语法:**
|
|
|
+```typescript
|
|
|
+@version version-text
|
|
|
+```
|
|
|
+
|
|
|
+**参数:**
|
|
|
+
|
|
|
+* *version-text*
|
|
|
+
|
|
|
+   版本号。
|
|
|
+
|
|
|
+**示例:**
|
|
|
+```typescript{2}
|
|
|
+/**
|
|
|
+ * @version 2.2.56
|
|
|
+ */
|
|
|
+export class SObject {
|
|
|
+ //
|
|
|
+}
|
|
|
+```
|