Browse Source

typedoc生成文档

haojianlong 4 years ago
parent
commit
9c48c60c6a
3 changed files with 409 additions and 1 deletions
  1. 2 1
      docs/.vuepress/config.js
  2. 4 0
      docs/standard/index.js
  3. 403 0
      docs/standard/typedoc.md

+ 2 - 1
docs/.vuepress/config.js

@@ -95,7 +95,8 @@ module.exports = {
                     {text: "javascript", link: "/standard/javascript.md"},
                     {text: "typescript", link: "/standard/typescript.md"},
                     {text: "约定", link: "/standard/appoint.md"},
-                    {text: "git", link: "/standard/git.md"}
+                    {text: "git", link: "/standard/git.md"},
+                    {text: "typescript 自动生成 api 文档", link: "/standard/typedoc.md"},
                 ]
             },
             {

+ 4 - 0
docs/standard/index.js

@@ -19,6 +19,10 @@ const content = [
         title: "git 提交规范",
         path: '/standard/git.md'
     },
+    {
+        title: "typescript 自动生成 api 文档规范",
+        path: '/standard/typedoc.md'
+    },
 ];
 
 module.exports = content;

+ 403 - 0
docs/standard/typedoc.md

@@ -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*
+
+&emsp;&emsp;    作者。
+
+**示例:**
+
+一个作者
+```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*
+
+&emsp;&emsp;    废除的原因。
+
+**示例:**
+```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*
+
+&emsp;&emsp;    抛出的异常类。
+
+* *description*
+
+&emsp;&emsp;    异常描述。
+
+**示例:**
+```typescript
+
+```
+
+
+### @param
+----
+函数入参。
+
+**语法:**
+```
+@param  parameter-name description
+```
+
+**参数:**
+
+* *parameter-name*
+
+&emsp;&emsp;    参数名。
+
+* *description*
+
+&emsp;&emsp;    参数描述。
+
+**示例:**
+
+函数入参
+
+```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*
+
+&emsp;&emsp;    返回值描述。
+
+**示例:**
+```typescript{5}
+/**
+ * 旋转变形
+ *
+ * @param   angle       绕 z 轴旋转角度(单位角度)
+ * @return  返回自身
+ */
+rotate(angle: number): SMatrix {
+    ......
+    return matirx;
+}
+```
+
+### @see
+----
+
+**语法:**
+```
+@see  reference
+```
+
+**参数:**
+
+* *reference*
+
+&emsp;&emsp;    参考对象。
+
+**示例:**
+```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*
+
+&emsp;&emsp;    起始版本。
+
+**示例:**
+```typescript
+/**
+ * @since   1.0.0
+ */
+export class SObject {
+    //
+}
+```
+
+### @version
+----
+版本号。
+
+**语法:**
+```typescript
+@version  version-text
+```
+
+**参数:**
+
+* *version-text*
+
+&emsp;&emsp;    版本号。
+
+**示例:**
+```typescript{2}
+/**
+ * @version 2.2.56
+ */
+export class SObject {
+    //
+}
+```