角度10 更好的Typescript源代码文档

在本教程中，我们将看到如何为Angular 10项目编写更好的Typescript源代码文档。文档可以帮助开发人员了解方法，类或参数的逻辑和功能。
您可以使用自动化的文档生成器来文档化项目，在该文档生成器中，我们不必为每个方法和类添加注释，但这是正在开发项目的开发人员无法立即找到文档的问题，因为文档生成器未添加源代码中对我们的注释。

Angular项目中的源代码文档

文档可以帮助开发人员了解开发人员代码背后的逻辑，即使开发人员进行了更改，也很容易将逻辑理解为传递的内容和不传递的内容。
可以为代码的每个部分逐一编写文档。

班级

最初，它是组件，服务，管道还是指令。它包含在类中。一个类可以通过其整体功能来记录。

/**
 * Class representing a list of products.
 */
@Component({...})
export class ProductListComponent implements OnInit {...}

如果该类扩展了其他一些类，我们可以记录该扩展类。

/**
 * Class representing a list of products.
 * @extends ProductType
 */
export class ProductListComponent extends ProductType {...}

@type（用于类属性）

在类内部，我们要做的基本事情就是声明类属性，我们可以通过两种方式（即通过注释和定义属性类型）来记录该属性。

  /**
   * Selected Product types
   * @type {string[] | null}
   * @public
   */
  public showProductType: string[] | null = null;
  // or
  /**
   * Selected Product types
   * @type {string[] | null}
   * @private
   */
  private showProductType: string[] | null = null;

@param和@returns

我们在课堂上做的另一件事是创建一个方法。该方法可以有两种：返回值的函数，另一种仅在函数内部执行逻辑的函数（即void类型）。这样，该方法还可以接受不同类型的参数，例如字符串，数字等。
具有返回类型和参数的函数

  /**
   * get the product count by its type
   * @param {string} type : ProductType Name
   * @return {number} count
   * @private
   */
  private getProductCount(type: string): number {
    return this.product[type].count;
  };

没有返回类型（void）并且具有多个参数的函数

  /**
   * set the product count by its type
   * @param {string} type : ProductType Name
   * @param {number} count : ProductType Count
   * @public
   */
  public setProductCount(type: string, count: number): void {
    this.product[type].count = count;
  };

@构造函数

当我们类似地记录方法的参数时，我们可以记录类构造函数及其参数。

  /**
   * @构造函数
   * @param {Router} router - The router service.
   * @param {RoutingState} routingState - The Routing State service.
   */
  constructor(
    private router: Router,
    private routingState: RoutingState
  ) {}

@usage注意事项

您还可以记录该方法的示例，以了解如何使用该方法以及对该特定方法有何期待。

/**
 *  @usage注意事项 
 * ### Retrieve a nested control
 * For example, to get a `name` control nested within a `person` sub-group:
 * * `this.form.get('person.name');`
 * -OR-
 * * `this.form.get(['person', 'name']);`
 */
get(path: Array<string | number> | string): AbstractControl | null;

更多
到目前为止，我们已经看到了日常使用的基本文档类型，您可以参考更多更详细的文档： 打字稿文档注释

使用CLI生成源代码文档

Compodoc 使您可以在几秒钟内生成文档，并可以创建项目的完整文档报告和体系结构。

# Install  Compodoc  with npm
$ npm install -g @compodoc/compodoc
# Run  Compodoc  in your project (generated with Angular CLI for example) and serve it
$  Compodoc  -p src/tsconfig.app.json -s

链接

应用程式： Compodoc
现场演示： Compodoc演示