Question

我们已设置 dgeni ，以便从我们现有的javascript文件中提取降价文档。我也试图将它扩展到解析打字稿文件。

我认为只需将.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解析打字稿文件吗？只是为了评论：

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

Answer 1

我在dgeni-packages/typescript之前添加了dgeni-markdown包，配置了readTypeScriptModules并确保文档直接位于导出之上。

const docs = new Package('docs', [
  require('dgeni-packages/typescript'),
  require('dgeni-markdown')
])
.config(function (readTypeScriptModules) {
  readTypeScriptModules.basePath = path.resolve(__dirname, '..');
  readTypeScriptModules.sourceFiles = [
    {
      include: 'src/main/javascript/**/*.ts',
      basePath: 'src/main/javascript'
    }];
});

确保文档直接位于导出之上。

/**
 * @ngdoc directive
 * @module we.components
 * @name contactSlideout
 * @restrict E
 *
 * @description
 * Der Tooltip-Teil vom Contact-Menü. Zu verwenden zusammen mit hmContactSlideout.
 *
 */
export default module.component('contactSlideout', {

添加打字稿支持的提交是：3e07adee8，适用于需要深入挖掘的人。

Answer 2

对于任何在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的好地方。

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

2 个答案: