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

我们已经设置 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.
 *
 */

最佳答案

对于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 repo是一个很好的地方，可以同时查看Typescript和dgeni。