Testing example code in doc comments

[rauschma]

Search terms

testing example code in doc comments

Question

I see two possible approaches. Both could probably be implemented via plugins(?) But I was wondering what the TypeDoc team thought and if any of them might get built-in support in the future. There could also be more approaches and/or tools that I’m not aware of.

Testing approach 1: include external code

async.ts:

/**
 * This function returns an iterable where each item was produced by applying
 * `mapperFn` to an item of `iterable`.
 * 
 * @example
 * {@includeCode
 *   ../../test/async-usage_test.ts#imports,
 *   ../../test/async-usage_test.ts#example-map,
 * }
 */

async-usage_test.ts:

//<section id="imports">
import * as assert from 'assert/strict';
import { AsyncIterable } from '@rauschma/iterable/async';
const {toArray, fromIterable: fi} = AsyncIterable;
//</section>

suite('async-usage_test.ts');

test('Using map()', async () => {
  //<section id="example-map">
  assert.deepEqual(
    await toArray(AsyncIterable.map(x => x + x, fi(['a', 'b', 'c']))),
    ['aa', 'bb', 'cc']
  );
  //</section>
  assert.deepEqual(
    await toArray(AsyncIterable.map(x => x + x, fi([]))),
    []
  );
});

Testing approach 2: export to JSON, test Markdown

async.ts:

/**
 * This function returns an iterable where each item was produced by applying
 * `mapperFn` to an item of `iterable`.
 * 
 * @example
 * ```ts
 * import * as assert from 'assert/strict';
 * import { AsyncIterable } from '@rauschma/iterable/async';
 * const {toArray, fromIterable: fi} = AsyncIterable;
 * assert.deepEqual(
 *   await toArray(AsyncIterable.map(x => x + x, fi(['a', 'b', 'c']))),
 *   ['aa', 'bb', 'cc']
 * );
 * ```
 */
async function* map<In, Out>(mapperFn: (x: In) => Out, iterable: AsyncOrSyncIterable<In>): AsyncIterable<Out> {
  for await (const x of iterable) {
    yield mapperFn(x);
  }
}

Processing:

• Use TypeDoc to create a JSON file with the documentation data.
• Use a modified version of my tool that runs code embedded in Markdown files: https://github.com/rauschma/markcheck

[Gerrit0]

Personally, I prefer option 1. #2816 will make it possible, (though you'll need two @includeCode tags, and it uses VSCode's folding syntax)

The biggest disadvantage with option 2 for me is that that code isn't tied into the language server at all. findAllReferences won't find it, renaming won't find it. It won't be checked for typos (without a tool such as yours which parses it out and runs it)

[rauschma]

Very nice! Looking forward to the next release.