为 Intern 4 功能测试自动生成文档答案

【问题标题】：Automatically generate documentation for Intern 4 functional tests为 Intern 4 功能测试自动生成文档
【发布时间】：2018-07-26 11:07:01
【问题描述】：

我想为 Intern 4 功能测试自动生成一些文档。我尝试了 typedoc，它在解析我的对象页面函数时效果很好，但是在功能测试套件上失败了，例如在像这样的文件上

/**
 * This is a test comment for general purpose
 */

/**
 *
 */
const { registerSuite } = intern.getInterface('object');

const { url } = intern.getPlugin('conf');

import { 
  tryLogin, 
  pollForDElement, 
  clickByDId,
  clickSeq,
  verifyGantt,
  verifyIcon,
  verifyCell
} from '../objectPage';


declare let ui: any;
let grid:string;
let id:string;


  registerSuite('cells-pre-test',
    {
      /** 
       * this is a test comment for a test 
       * 
       */
      'login'()
      {
        return this.remote
          .setFindTimeout(20000)
          .setPageLoadTimeout(20000)
          .setExecuteAsyncTimeout(20000)
          .get(url)
          .then(tryLogin('xxx', 'xxx'));
      }
    });

用命令

typedoc --module commonjs --target ES6 --out docs/ tests/

生成的文档中只显示一般用途的注释，而不是测试套件的注释。

任何人都可以帮助我解决这个问题或建议使用自动 Typescript 解析的替代工具吗？

谢谢

【问题讨论】：

标签： typescript intern typedoc

【解决方案1】：

Typedoc 仅提取特定类型元素的 cmets，例如模块、导出函数、类和类成员。测试函数没有什么特别的地方（它只是泛型对象中的一个方法），所以 Typedoc 不关注任何相关的 cmets。（见https://github.com/TypeStrong/typedoc/issues/821。）

我不知道有任何 JS 或 TS 文档工具可以提取测试 cmets。一种可能性是使用 Typedoc 的 JSON 输出功能 (typedoc --json <json file>) 来输出项目的 JSON 描述。然后，您可以编写一个工具来遍历 JSON 数据以查找 doc cmets 并根据它找到的内容创建一个 doc 文件。这可能最适合使用某种自定义 doc 标签，例如 @test，以便该工具可以识别哪些 cmets 与测试相关。

【讨论】：