javascript - 如何使用 dgeni 解析 typescript 文件中的文档注释

Question

我们已经设置 dgeni 从我们现有的 javascript 文件中提取 Markdown 文档。我也在尝试扩展它来解析 typescript 文件。

我认为只需将 .ts 文件添加到 sourceFiles include 中就可以解决问题，但它会引发一些错误:

error:   Error processing docs:  Error: No file reader found for javascript/components/main.ts
  at matchFileReader (node_modules\dgeni-packages\base\processors\read-files.js:130:25)
  at node_modules\dgeni-packages\base\processors\read-files.js:66:99
  at <anonymous>

我发现了一些像 dgeni-packages:3e07adee84b7a795a0fb02d7181effa593fb9b4f 这样的提交我再次搜索并搜索如何设置 dgeni。

我们生成我们的文档:

'use strict';

const path = require('canonical-path');
const {Dgeni, Package} = require('dgeni');

const docs= new Package('docs', [
  require('dgeni-markdown')
])
  .processor(require('./indexPage'))
  .config(function (log, readFilesProcessor, writeFilesProcessor, templateFinder, apiPagesProcessor) {
    log.level = 'warn';
    readFilesProcessor.basePath = path.resolve(__dirname, '..');
    readFilesProcessor.sourceFiles = [
      {
        include: 'src/main/javascript/**/*.js',
        basePath: 'src/main/javascript'
      },
    ];
    templateFinder.templateFolders.unshift(path.resolve(__dirname, 'templates'));
    apiPagesProcessor.pathFromOutputToRootFolder = '../..';
    writeFilesProcessor.outputFolder = 'docs/generated';
  });
const dgeni = new Dgeni([docs]);

module.exports = () => dgeni.generate().then(done);

dgeni.generate().then(done);

function done() {
  console.log('Generated documentation.');
}

有没有简单的方法让 dgeni 也能解析 typescript 文件？仅针对以下评论:

/**
 * @ngdoc directive
 * @module we.components
 * @name contactSlideout
 * @restrict E
 *
 * @description
 * Contact Slideout.
 *
 */

Answer 1

对于 2019 年或之后来到这里的任何人，dgeni 自接受的答案以来发生了一些变化。 dgeni-markdown 不存在了。以下是我如何让 dgeni 正确解析 Typescript:

import { Categorizer } from "../processors/categorizer";
import * as path from 'path';
import { Package } from "dgeni";

const jsdocPackage = require('dgeni-packages/jsdoc');
const nunjucksPackage = require('dgeni-packages/nunjucks');
const typescriptPackage = require('dgeni-packages/typescript');

export let checkoutDocs =  new Package('checkout', [
  jsdocPackage,
  nunjucksPackage,
  typescriptPackage
]);

// This processor organizes what the typescriptPackage has tagged into objects that can be easily read by our templates.
checkoutDocs.processor(new Categorizer());

// Configure our dgeni-example package. We can ask the Dgeni dependency injector
// to provide us with access to services and processors that we wish to configure
checkoutDocs.config(function(readFilesProcessor, log, writeFilesProcessor, templateFinder, readTypeScriptModules, templateEngine) {

  // Set logging level
  log.level = 'info';

  // The typescriptPackage only uses the "readTypeScriptModules" processor, so disable readFilesProcessor.
  readFilesProcessor.$enabled = false;

  // Specify the base path used when resolving relative paths to source and output files
  readTypeScriptModules.basePath = path.resolve(__dirname, '../..');

  // Specify collections of source files that should contain the documentation to extract
  readTypeScriptModules.sourceFiles = [
    {
      // Process a single file for now
      include: 'src/billing/containers/billing.component.ts',
      basePath: 'src'
    }
  ];

  // Nunjucks and Angular conflict in their template bindings so change Nunjucks
  templateEngine.config.tags = {
    variableStart: '{$',
    variableEnd: '$}',
  };

  // Add a folder to search for our own templates to use when rendering docs
  templateFinder.templateFolders.unshift(path.resolve('./docs/templates'));

  // Specify how to match docs to templates.
  templateFinder.templatePatterns.unshift('common.template.html');

  // Specify where the writeFilesProcessor will write our generated doc files
  writeFilesProcessor.outputFolder  = path.resolve('./docs/build');
});

另外，评论不应该总是直接在 export 上面，正如接受的答案所指出的那样。我发现在 Angular 中，对于 Component 的注释只有在 @Component 之上时才会被拾取:

/**
 * Billing Container description to be picked up by dgeni.
 */
@Component({
  selector: '[billing-container]',
  template: '<ng-content></ng-content>',
  exportAs: 'BillingContainer'
})
export class BillingContainer {
}

如果您正在寻找更多信息，Angular Material 存储库是查看 Typescript 和 dgeni 一起运行的好地方。