apidocのその先
podhmo
果たしてapidocを繋げる先はUMLなのか用例なのかintegration testなのかtutorialなのか
podhmoUML
あんまり記憶にないが図示というとUMLを思い浮かべる。個人的には実装との接続がないのでUMLにはあんまり期待していない。メンテされないことが多いので。
とはいえ可視化ということを考えると基本的には以下2つに絞られそう
- 静的な構造を図示するクラス図
- 動的な呼び出し関係を図示するシーケンス図
より詳細度が低く上流ではユースケース図のようなものも使われるかもしれない。アクティビティ図（フローチャート）も同様。
どこから何を引っ張ってくるかを知りたいのだからこれらは適切ではないような気がする
podhmo地図
実際のところほしいのは地図なんだろうか？例えば最近眺めた上ではPythonのコードの在り処が書かれたものは参考になった。
またarchitecture.mdを書くべきみたいな記事を良く見かけた気がする
podhmoこういうプロジェクト単位の概念的な地図が欲しくなるというのは共感するものの考えたいのはもう少し粒度の細かいもののような気がする。
ちなみに、この概念図の類似のものとして用語集（glossary）があったりする。
podhmoapidoc
そもそもapidocでは不満だと言っていたがapidocとは何かを明示してなかった。
単純に言えばopenapi docで表せられるようなものだし
sphinx-autodocみたいにdocstringで表せるようなもの。関数定義と一対一のコメントのようなものを思い浮かべれば良い。
（おそらくここでも機能の紹介というよりは用例をリンクとして貼るべきかもしれない）
pkg.go.devなんかも同様。
podhmo方針
何を求めるかによって方針は代わる
- 整合性 integration tests
- 利用方法の説明 用例/チュートリアル/ガイド
- 一望したり検索したり ？？？？ （markdown? fuzzy find？）
- PCではなくスマホでみたい
podhmo整合性 integration tests
通常api docは関数などの1ユニットと1:1になっている。コードの実行例などがドキュメントととして載ってることもある。
これは嬉しいのだけれど実際に欲しいのはこのユニット同士の組み合わせ方という感じ。つまりテストでいえばユニットテストに対する結合テストのようなものが欲しくなる。
これはいわゆる逆引きレシピみたいなものだったりgetting startedのところで作られるサンプルプロジェクトで説明されることもある。
とはいえ、すべてに丁寧な用例を作るのはコストが高過ぎる。一方で、関数同士の関係のようなものをどうにかドキュメントととして手軽に残すことはできないか？と思ってはしまう。
podhmoパッケージ内の依存関係
- パッケージ内の依存関係
- パッケージ間の依存関係
前者を考えてみると、特定のパッケージの中でのトップレベル関数は何か？というのが見えてくるかもしれない。
podhmo頻度情報
例えばgoのtestifyは大量に関数を持っているが使われてるアサーション関数は極一部だったりする。
こういうときには頻度情報的なものを利用して利用頻度順にソートされてたりすると嬉しい。あるいはopacityのようなものが設定されていてほとんど使われていないものに関しては透明に近く表示されてると嬉しい。
とはいえこれは利用者目線の話。