本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 开发和完善文档
<a name="documentation-best-practices"></a>

文档对于项目的成功至关重要。文档不仅解释了代码的工作原理，还可以帮助开发人员更好地了解应用程序的特性和功能。开发和完善高质量的文档可以加强软件开发过程，保持软件的高质量，并有助于开发人员之间的知识转移。

文档分为两类：代码中的文档和有关代码的支持文档。代码中的文档采用注释的形式。有关代码的支持文档可以是 README 文件和外部文档。开发人员将文档视为开销的情况并不少见，因为代码本身很容易理解。对于小型项目来说可能是这样，但是对于涉及多个团队的大型项目来说，文档至关重要。

对于代码的作者来说，最好的做法是编写文档，因为他们对文档的功能有很好的了解。开发人员可能会为维护单独的支持文档的额外开销而苦恼。为了克服这一挑战，开发人员可以在代码中添加注释，这些注释可以自动提取，这样每个版本的代码和文档都将保持同步。

有多种不同的工具可以帮助开发人员从代码中提取注释并生成文档。本指南重点介绍如何 TypeDoc将其作为 AWS CDK 构造的首选工具。

## 为什么 AWS CDK 构造需要代码文档
<a name="code-docs-constructs"></a>

AWS CDK 通用结构由组织中的多个团队创建，并在不同的团队之间共享以供使用。好的文档有助于构造库的使用者轻松集成构造，并以最小的代价构建自己的基础设施。保持所有文档同步是一项艰巨的任务。我们建议您将文档保存在代码中，该文档将使用TypeDoc库进行提取。

## TypeDoc 与 AWS 构造库一起使用
<a name="typedoc-constructs"></a>

TypeDoc 是的文档生成器 TypeScript。您可以使用读 TypeDoc 取 TypeScript 源文件，解析这些文件中的注释，然后生成包含代码文档的静态站点。

以下代码向您展示了如何 TypeDoc 与 C AWS onstruct 库集成，然后在`package.json`文件中添加以下包`devDependencies`。

```
{

  "devDependencies": {
   
    "typedoc-plugin-markdown": "^3.11.7",
    "typescript": "~3.9.7"
  },
  
}
```

若要在 CDK 库文件夹中添加 `typedoc.json`，请使用以下代码。

```
{
    "$schema": "https://typedoc.org/schema.json",
    "entryPoints": ["./lib"],
}
```

要生成 README 文件，请在 AWS CDK 构造库项目的根目录中运行该`npx typedoc`命令。

以下示例文档由生成 TypeDoc。

![示例 TypeDoc 文档](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/best-practices-cdk-typescript-iac/images/sample_typedoc_1.png)


有关 TypeDoc 集成选项的更多信息，请参阅[文档中的 TypeDoc 文档注释](https://typedoc.org/guides/doccomments/)。