JavaScript项目的文档通常是通过作为代码注释插入的注释来生成的。虽然这能完成任务，但似乎还远不理想。在这篇文章中，我将探讨如何使用TypeScript单独从源代码生成文档。大卫·乔伊纳的CC BY-SA 2.0图像TypeScript是具有可选类型的JavaScript。下面是一个简单的例子：//将一些数据发送到某个分析终结点函数发送分析SJS（数据）{如果（类型数据类型!=='字符串'）{throw new Error（'type`property is required'）}导航器.发送信标（'/信标'，JSON.stringify（数据）}//导致运行时错误//需要"type"属性sendAnalyticsJS（{foo:'bar'}）JavaScript代码将导致运行时错误。如果开发人员及早发现它，这是很好的，但是如果在引入bug时警告开发人员，则会更好。下面是用TypeScript编写的相同代码：//描述数据参数的形状接口IAnalyticsData{//类型是必需的类型：字符串//其他领域都是公平竞争[propName:string]：字符串}//我们并不特别需要数据类型从那以后在这里查一下//编译器将清除其中的大多数情况。函数sendAnalytics（数据：IAnalyticsData）{如果（类型数据类型!=='字符串'）{throw new Error（'type`property is required'）}导航器.发送信标（'/信标'，JSON.stringify（数据）}//导致编译时错误：//"{foo:string；}"类型的参数不能赋值给//"IAnalyticsData"类型的参数。//类型{foo:string；}中缺少属性"type"。sendAnalytics（{foo:'bar'}）这些注释都是可选的，添加的越多，编译器就越能帮助您。编译TypeScript版本将生成与第一个示例等效的代码。唯一的区别是开发人员在编写代码时会收到错误警告。有了TypeScript，JavaScript开发人员就可以获得强大的工具来帮助开发大大小小的应用程序。TypeScript的C和核心开发的首席架构师andershejlsberg将这种语言描述为"可伸缩的JavaScript"使用TypeScript意味着您可以：从文本编辑器交互式地浏览库接口享受有用的自动完成使用好的重构工具通过描述代码库的本体来导航代码库（我指的是从单个实例/引用跳转到类和接口定义、模块等）对于这篇文章来说，最重要的是，生成与代码库紧密耦合的文档。上面的屏幕截图是Cloudflare的TypeScript项目生成的文档。为什么不是JSDoc？用JSDoc注释注释源代码所需的工作量相当于采用TypeScript注释。但是，JSDoc注释并没有与代码库紧密耦合，因此当代码发生变化时，还需要对JSDoc注释进行独立的更改。与TypeScript相反，TypeScript的结构直接从源代码中收集。下面是JSDoc和TypeScript的并排比较：JSDoc公司/***代表一个点的类*@班级积分*/班级积分{/***创建一个点。*@param{number}x-x值。*@param{number}y-y值。*/构造器（x，y）{/***x坐标*@name Point#x点*@type{number}*/这个.x=x/***y坐标*@名字点*@type{number}*/这个.y=y}/***得到x值。*@return{number}x值。*/获取X（）{返回此.x}/***得到y值。*@return{number}y值。*/盖蒂（）{把这个还给我}/***将包含两个逗号分隔的数字的字符串转换为一个点。*@param{string}str-包含两个逗号分隔数字的字符串。*@return{Point}一个Point对象。*/静态fromString（str）{常量参数=结构分裂（'，'）.map（arg=>+arg）返回新点（args[0]，args[1]）}}打字稿/**类表示一个点。*/班级积分{/**x坐标*/公共x:编号/**x坐标*/公共y:编号/***创建一个点。*@param x-x值。*@param y-y值。*/构造器（x:编号，y:编号）{这个.x=x这个.y=y}/***得到x值。*/获取X（）{返回此.x}/***得到y值。*/盖蒂（）{把这个还给我}/***将包含两个逗号分隔的数字的字符串转换为一个点。*@param str-包含两个逗号分隔数字的字符串。*/静态fromString（str:string）：点{常量参数=结构分裂（'，'）.map（arg=>+arg）返回新点（args[0]，args[1]）}}上面的代码示例取自JSDoc文档，适合与TypeScript一起使用。TypeScript的注释更紧凑，语法突出显示，最重要的是，如果出现错误，编译器会告诉我们。对事物的长形式描述仍然在注释中进行，但是类型信息已经转移到语言语义中。采用TypeScript的缺点是需要大量的工作来将构建工具安装到当前流程中。然而，我们不会关注构建工具的细节，因为生态系统正在迅速变化。使用TypeDoc在Cloudflare，我们使用一个名为TypeDoc的工具来帮助构建文档。它的设置使得文档生成处于监视状态，并将在代码库更改的基础上重新构建。任何对项目进行黑客攻击的人都会在本地主机：3000个/文档。如果使用的是TypeScript 2.x，请使用以下命令为项目安装TypeDoc：npm install—保存开发https://github.com/DatenMetzgerX/typedoc/tarball/typescript-2-build否则，对于以前版本的TypeScript，可以直接从NPM安装：npm install—保存dev typedoc在项目目录中，运行以下命令：#将--out标志更改为要存储输出的位置./node_modules/.bin/typedoc--out dist/docs--模式模块。您应该会看到生成了一堆HTML文档。每个班级和模块一个。分发/文档├—资产│–├—css│ │ ├── 主.css│ │ └── main.css.map│–├—图像│ │ ├── 图标.png│ │ ├── icons@2x.png│ │ ├── 小工具.png│ │ └── widgets@2x.png│-js│ ├── 主.js│ └── 搜索.js├—班│–├—我的_类.html│ └── ...├── 全局.html├── 索引.html├—接口│ ├── _src.my_接口.html格式———模块├—_src_my_模块_u.html└── ...我想构建类似于Lodash文档的东西（一个漂亮的单页API引用，包含示例和源代码链接）。幸运的是，您可以使用TypeDoc的--json标志以json格式生成一组有用的代码库描述。./node\u modules/.bin/typedoc--json dist/docs.json文件--模式模块注意：为了使用--json标志，您需要设置适当的tsconfig.json文件你的TypeScript项目。有了对代码库的高级结构化描述，我们可以用一些脚本和类似手柄的模板语言来呈现我们想要的任何HTML。下面是一个用于呈现代码基模块列表的简单脚本：const fs=要求（'fs'）const hbs=需要（"车把"）const project=需要（'./dist/docs.json文件')//用于简单文档的HTML模板常数tmpl=`在在模块{{每个项目.儿童}}