整理: ユーザー辞書のdocstring・変数名・型・コメント

[tarepan]

内容

ユーザー辞書モジュールへのdocstring・変数名・型・コメント追加によるリファクタリング

関連 Issue

• part of docstringの整備 #59
• related to コーディング規約集 #799, コーディング規約 No.1

[github-actions]

Coverage Result

Resultを開く

Name	Stmts	Miss	Cover
run.py	481	327
voicevox_engine/init.py	1	0
voicevox_engine/acoustic_feature_extractor.py	19	1
voicevox_engine/cancellable_engine.py	91	71
voicevox_engine/dev/core/init.py	2	0
voicevox_engine/dev/core/mock.py	27	12
voicevox_engine/dev/synthesis_engine/init.py	2	0
voicevox_engine/dev/synthesis_engine/mock.py	38	2
voicevox_engine/engine_manifest/EngineManifest.py	34	0
voicevox_engine/engine_manifest/EngineManifestLoader.py	12	0
voicevox_engine/engine_manifest/init.py	3	0
voicevox_engine/full_context_label.py	162	3
voicevox_engine/kana_parser.py	86	1
voicevox_engine/library_manager.py	93	5
voicevox_engine/metas/Metas.py	33	0
voicevox_engine/metas/MetasStore.py	29	12
voicevox_engine/metas/init.py	2	0
voicevox_engine/model.py	162	9
voicevox_engine/mora_list.py	4	0
voicevox_engine/morphing.py	70	46
voicevox_engine/part_of_speech_data.py	5	0
voicevox_engine/preset/Preset.py	12	0
voicevox_engine/preset/PresetError.py	2	0
voicevox_engine/preset/PresetManager.py	81	2
voicevox_engine/preset/init.py	4	0
voicevox_engine/setting/Setting.py	11	0
voicevox_engine/setting/SettingLoader.py	19	0
voicevox_engine/setting/init.py	3	0
voicevox_engine/synthesis_engine/init.py	5	0
voicevox_engine/synthesis_engine/core_wrapper.py	202	147
voicevox_engine/synthesis_engine/make_synthesis_engines.py	59	30
voicevox_engine/synthesis_engine/synthesis_engine.py	139	13
voicevox_engine/synthesis_engine/synthesis_engine_base.py	71	10
voicevox_engine/user_dict.py	144	12
voicevox_engine/utility/init.py	5	0
voicevox_engine/utility/connect_base64_waves.py	37	0
voicevox_engine/utility/core_version_utility.py	8	1
voicevox_engine/utility/mutex_utility.py	10	0
voicevox_engine/utility/path_utility.py	26	8
TOTAL	2194	712

[Hiroshiba]

ほぼLGTMです！！

これはどうするのが最適なのかわからないのでちょっと聞いてみてる感じなのですが、ぱっと見で役割が想像できるようなプライベート関数の引数にもドキュメントを付けると、次はそのコメントのメンテナンスが大変になりそうだなと思えてきました。
かといって何もないのはそれはそれで読みづらいのと、付ける付けないのルールを考えるのも難しいのとで、どう考えれば良いか方針ご存知でしたら知りたいなくらいの気持ちです！

[tarepan]

ぱっと見で役割が想像できるようなプライベート関数 ... ドキュメント ... メンテナンスが大変

はい、同意です。
プライベート関数は手軽に変更しやすく（だから unittest も無くていい）という観点からは、フォーマルなdocstringは過剰だと思います。

何もないのはそれはそれで読みづらい ... 付ける付けないのルールを考えるのも難しい ... 方針ご存知でしたら

そう言われてみると、これに関する best practice を見たこと無い気がします。
今まで join したプロジェクトでも明確な方針は無かったですね。

私が個人プロジェクトでよく採用するのは「パッケージ外に public な関数は formal docstring 必須」「他の関数は、機能ベース関数名 + 型エイリアス で上手く表現できたら、formal docstring のワンライナー化許可」です。

これを：

def _write_to_json(user_dict: Dict[str, UserDictWord], user_dict_path: Path) -> None:
    """
    ユーザー辞書ファイルへのユーザー辞書データ書き込み
    Parameters
    ----------
    user_dict : Dict[str, UserDictWord]
        ユーザー辞書データ
    user_dict_path : Path
        ユーザー辞書ファイルのパス
    """

こうする感じ：

WordID = str
Dictionary = Dict[WordID, Word]

def _write_user_dict(user_dict: Dictionary, user_dict_path: Path) -> None:
    """ユーザー辞書データをパスで指定したユーザー辞書ファイルへ書き込む"""

[Hiroshiba]

@tarepan
簡易的なドキュメント、良さそうに思いました！
そもそもユーザー向けのドキュメントではないので、パブリックの関数ももっと簡易的なものでもいいかもですね。
引数の横にコメント書くとか。まあdocstringにならないのですが、引数名をコピペする手間が省けるなぁと。

def hoge(
  arg1: str,  # この引数のコメント
)

[Hiroshiba]

LGTM！！！