ドキュメントとテストを対応関係にする

[FineArchs]

ドキュメントファイル(.md)とテストコード(.ts)を、それぞれお互いに同名の対応するファイルがあるようにしたいと考えています。

// 例
doc/
  get-started.md, syntax.md, std.md, std-math.md, primitive-props.md
  parser/
    scanner.md

test/
  get-started.ts, syntax.ts, std.ts, std-math.ts, primitive-props.ts, parser.ts
  // パーサーのドキュメント・テストはひとまず現状維持とする

Pros

• テストが探しやすくなる。
• 足りていないテストを確認しやすくなる。

Cons

• ややテスト時間が伸びる？
• ややメンテナンスコストが上がる？

[marihachi]

基本的には仕様に対してテストをするようにしたいですね。
ただ、仕様と関係のない実装に対するテストがあるかも知れないので、そのテストはドキュメントと対応してこないかなと思います。

[marihachi]

ドキュメントにもいろいろ種類があると思っています。
テストと対応させるのは、言語仕様のドキュメントが良いかと思います。
機能や構文を説明するドキュメントには、詳細な仕様は書けないと思うので。

[FineArchs]

ドキュメントを説明用と仕様制定用に分ける感じですね。
説明用の方にもテストを用意することにもメリットがあると考えていますが（仕様変更時にドキュメントの書き換えが必要な箇所をテストで検知出来る）、少なくとも後回しになりますね

[takejohn]

これdoctestみたいにMarkdown内のコードブロックをAiScriptとして実行できたら便利そうですね
Markdownのパーサを使用してコードブロックを抽出したり、AiScriptにassert関数を追加したりしたらいい感じにできそう

[FineArchs]

求：いい感じのMarkdownパーサ

related?: #804

[uzmoi]

vitepress なら markdown-it で starlight なら unified/remark 使ってるのでサイトジェネレータと同じものを使うとよいと思います。
サイトの中だとそれを使うことになるので。

あと、ユーザーが読むことを考慮するなら https://github.com/azu/power-doctest のように1 + 1 // => 2みたいな書き方ができると読みやすいかなと思いました。

[takejohn]

あと、ユーザーが読むことを考慮するなら https://github.com/azu/power-doctest のように1 + 1 // => 2みたいな書き方ができると読みやすいかなと思いました。

power-doctestは@babel/parserが生成するASTからtrailingCommentsを読み取ってるっぽい
AiScriptのASTにコメントの情報は残らないのでパーサの変更が必要そう