Open10
apidocのその先
![podhmo](https://res.cloudinary.com/zenn/image/fetch/s--GWKFblck--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_70/https://storage.googleapis.com/zenn-user-upload/avatar/27cc184596.jpeg)
果たしてapidocを繋げる先はUMLなのか用例なのかintegration testなのかtutorialなのか
![podhmo](https://res.cloudinary.com/zenn/image/fetch/s--GWKFblck--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_70/https://storage.googleapis.com/zenn-user-upload/avatar/27cc184596.jpeg)
UML
あんまり記憶にないが図示というとUMLを思い浮かべる。個人的には実装との接続がないのでUMLにはあんまり期待していない。メンテされないことが多いので。
とはいえ可視化ということを考えると基本的には以下2つに絞られそう
- 静的な構造を図示するクラス図
- 動的な呼び出し関係を図示するシーケンス図
より詳細度が低く上流ではユースケース図のようなものも使われるかもしれない。アクティビティ図(フローチャート)も同様。
どこから何かを引っ張ってくるかを知りたいのだからこれらは適切ではないような気がするを
![podhmo](https://res.cloudinary.com/zenn/image/fetch/s--GWKFblck--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_70/https://storage.googleapis.com/zenn-user-upload/avatar/27cc184596.jpeg)
地図
実際のところほしいのは地図なんだろうか?例えば最近眺めた上ではPythonのコードの在り処が書かれたものは参考になった。
またarchitecture.mdを書くべきみたいな記事を良く見かけた気がする
![podhmo](https://res.cloudinary.com/zenn/image/fetch/s--GWKFblck--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_70/https://storage.googleapis.com/zenn-user-upload/avatar/27cc184596.jpeg)
apidoc
そもそもapidocでは不満だと言っていたがapidocとは何かを明示してなかった。
単純に言えばopenapi docで表せられるようなものだし
sphinx-autodocみたいにdocstringで表せるようなもの。関数定義と一対一のコメントのようなものを思い浮かべれば良い。
(おそらくここでも機能の紹介というよりは用例をリンクとして貼るべきかもしれない)
pkg.go.devなんかも同様。
![podhmo](https://res.cloudinary.com/zenn/image/fetch/s--GWKFblck--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_70/https://storage.googleapis.com/zenn-user-upload/avatar/27cc184596.jpeg)
方針
何を求めるかによって方針は代わる
- 整合性 integration tests
- 利用方法の説明 用例/チュートリアル/ガイド
- 一望したり検索したり ???? (markdown? fuzzy find?)
- PCではなくスマホでみたい