docstringの整備

[y-chan]

内容

CI整備(#16)と一緒にやってます( https://github.com/Hiroshiba/voicevox_engine/issues/16#issuecomment-907324672 )が、一応CI整備とは異なる分野なので、別でIssueを立てておきます。

Pros 良くなる点

コードが理解しやすくなる(サードパーティー製エンジンの作成や、これからの改善がしやすくなる)

Cons 悪くなる点

おそらくない(あって全体のコード行数が長くなるくらい...?)

実現方法

NumPyスタイルでdocstringを記述していく。

[Hiroshiba]

良いですね！　アサインさせていただきます 🙏

[y-chan]

最近はCIもdocstringもまともに整備できてないですが、NumPyスタイルではないコメント(OpenAPIにdescriptionとして含まれるModelは除く)が増えてきている気がするので、それらを統一するのもこのIssue内でやってしまいたい気がしますね...

[tarepan]

現状

docstring整備がある程度進行。

また、NumPyスタイル docstring のメンテコストが高いという意見あり。

ユーザー向けのドキュメントではないので、パブリックの関数ももっと簡易的なものでもいいかも
Hiroshiba #836 comments

将来

@Hiroshiba
こちらの issue では NumPy スタイル docstring の推進という方針です。
もし今後「全関数へは付与はしない」という方針であれば、docstring 整備が一定の成果を挙げたということで本 issue は close 可能かと思います。

[Hiroshiba]

@tarepan ドキュメントの付与ありがとうございました！！！　コードが全体的にとても読みやすくなったと思います！！！

ドキュメントをそもそもどれくらい書くべきなのか、ベストプラクティスをちょっと調べてみました。
驚いたんですが、基本的に引数の説明も書く方針が案内されていました。
https://github.com/google/styleguide/blob/gh-pages/docguide/best_practices.md
https://coderslegacy.com/python/best-practices-for-docstrings/

まあとはいえ同じ文書内で書かれてる「正確で小さなコメントのが良い」と反することもあるので、適宜調整な雰囲気を受けました。
仮にドキュメントのガイドラインを作るなら、こうとかですかねぇ。

• 完結で正確なコメント・ドキュメントを書く
• メソッド・関数・クラスのドキュメントはあったほうが良い
• 引数・返り値・起こりうるエラーもあったほうが良い
• 自明な場合はなくても良い

もし今後「全関数へは付与はしない」という方針であれば

その方針で良いのかなと！！
ということでcloseしたいと思います！　@y-chan さん的に思うところがあればコメントいただければ！

ありがとうございました！！！