Repository navigation
ドキュメントとテストを対応関係にする #438
Description
ドキュメントファイル(.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
- ややテスト時間が伸びる？
- ややメンテナンスコストが上がる？
Metadata
Metadata
Assignees
Labels
No labels
Activity
marihachi commentedon Nov 10, 2023
基本的には仕様に対してテストをするようにしたいですね。
ただ、仕様と関係のない実装に対するテストがあるかも知れないので、そのテストはドキュメントと対応してこないかなと思います。
marihachi commentedon Nov 10, 2023
ドキュメントにもいろいろ種類があると思っています。
テストと対応させるのは、言語仕様のドキュメントが良いかと思います。
機能や構文を説明するドキュメントには、詳細な仕様は書けないと思うので。
FineArchs commentedon Nov 10, 2023
ドキュメントを説明用と仕様制定用に分ける感じですね。
説明用の方にもテストを用意することにもメリットがあると考えていますが（仕様変更時にドキュメントの書き換えが必要な箇所をテストで検知出来る）、少なくとも後回しになりますね
takejohn commentedon Oct 27, 2024
これdoctestみたいにMarkdown内のコードブロックをAiScriptとして実行できたら便利そうですね
Markdownのパーサを使用してコードブロックを抽出したり、AiScriptにassert関数を追加したりしたらいい感じにできそう
FineArchs commentedon Oct 27, 2024
求：いい感じのMarkdownパーサ
related?: #804
uzmoi commentedon Oct 27, 2024
vitepress なら markdown-it で starlight なら unified/remark 使ってるのでサイトジェネレータと同じものを使うとよいと思います。
サイトの中だとそれを使うことになるので。
あと、ユーザーが読むことを考慮するなら https://github.com/azu/power-doctest のように
1 + 1 // => 2みたいな書き方ができると読みやすいかなと思いました。takejohn commentedon Dec 6, 2024
power-doctestは@babel/parserが生成するASTから
trailingCommentsを読み取ってるっぽいAiScriptのASTにコメントの情報は残らないのでパーサの変更が必要そう