シンボルトランスクルージョン
関数名へのwiki-リンクを書くと、シンタックスハイライト付きで関数本体がその場に表示され、ソースファイルから直接引き出されます。AST駆動の抽出は40以上の言語に対応：Python、Swift、JavaScript、TypeScript、Go、Rust、Java、C、C++、Ruby、Kotlinなど。ソースを編集すれば、ドキュメントが更新されます。
# 関数を名前で埋め込み
![[auth.py#validate_token]]Ohaiはauth.pyからvalidate_token関数を抽出し、シンタックスハイライト付きでインライン表示。関数が変更されれば、ドキュメントも自動的に更新されます。
なぜ重要か
従来のドキュメントは腐ります。コードをマークダウンにコピー＆ペーストし、コードが進化すると、突然ドキュメントが嘘をつき始めるのです。シンボルトランスクルージョンは、ソースファイルを唯一の信頼できる情報源として扱うことで、この問題を解決します。
リファクタリングのたびに壊れる行番号参照とは異なり、シンボルトランスクルージョンはAST解析を使って、関数、クラス、構造体、定数といった実際の名前でコードを見つけます。ファイル名を変更しても、コードを再構成しても、新しいメソッドを追加しても、シンボル名が存在する限り、ドキュメントは正確さを保ちます。
活用例
APIドキュメント
手入力で同期がずれた近似版ではなく、実際の関数シグネチャを参照できます。
アーキテクチャ決定記録
ADRで議論しているコードを埋め込み。コードベースの進化に合わせて、例も最新の状態を保ちます。
オンボーディングガイド
リポジトリと一致すると信頼できる生きたコードで、新しい開発者に認証の仕組みを示せます。
コードレビュー
特定の関数をマークダウンサマリーに取り込み、非同期でレビューや議論を行えます。
チュートリアル
実際の実装を段階的に解説。読者はコード例が常に最新であると信頼できます。
ランブック
インシデント時に運用チームが参照する必要がある、正確な設定やスクリプトを埋め込めます。
対応言語
Tree-sitter ASTパースでPython、Swift、JavaScript、TypeScript、Go、Rust、Java、C、C++、Ruby、Kotlin、PHP、Scala、Haskell、OCaml、Lua、Elixir、Bashなどに対応 — さらにデータ形式のパス抽出機能でJSONキー、YAMLパス、TOMLテーブル、plistパス、XML、CSS、SQL、プレーンテキストにも対応。合計40以上の形式。
古くならないドキュメントを試してみませんか？
Mac版をダウンロード