使用JSDoc注释Angular 2 / Ionic 2项目

Question

我正在尝试使用JSDoc对我的Ionic 2应用程序进行文档编写，但是我在使用它与Angular 2的语法时遇到了困难。

例如，在我的应用程序顶部有以下代码：

import {App, Events, IonicApp, Platform} from 'ionic-framework/ionic';
import {UserData} from './providers/user-data';

@App({
  templateUrl: 'build/app.html',
  providers: [UserData],
  config: {

  }
})

尝试解析该文件时，由于@App，JSDoc报错如下：

ERROR: 无法解析 /home/user/Projects/mobileApp/app/app.js: 第4行：Unexpected token ILLEGAL

此外，我的构造器看起来像这样（使用了Ionic 2的教程模板）：

class MyApp {
  constructor(app: IonicApp, platform: Platform, events: Events, userData: UserData) {

  }
}

这会导致错误：

ERROR: 无法解析 /home/user/Projects/mobileApp/app/app.js: 第27行：意外的标记 :

请问有人能告诉我如何避免这些错误吗？

感谢任何帮助。

- Daniel Hutton

Answer 1

Angular2使用TypeScript进行增强，但它实际上并不是JavaScript，所以JSDoc无法理解它。建议尝试使用typedoc： http://typedoc.org/

- Rytis Alekna

---

谢谢，我会去看一下。我正在使用Ionic2和Angular2的Javascript版本，而不是typescript，这仍然适用吗？ - Daniel Hutton

在您提供的示例中，您正在使用TypeScript（类型注释，装饰器）。当然，在运行时（或部署时），您的应用程序将被转译为原始JavaScript（没有浏览器直接支持TypeScript）。有关TypeScript和JavaScript之间差异的更多解释，请参见https://dev59.com/XWcs5IYBdhLWcg3woFft。 - Rytis Alekna

TypeDoc非常好用，感谢您的建议。我也尝试使用Ionic的TypeScript版本，它似乎越来越受欢迎，所以学习一下也无妨。 - Daniel Hutton

Answer 2

在将 ES7 JS 代码提供给 JSDoc 之前，应该通过 Babel 转译为 ES5 或通过 TypeScript 转译为 ES6（.js 文件重命名为 .ts）。

文档构建过程可能与应用程序捆绑过程无关。

- Estus Flask