ドキュメントを刷新する (#532)

Co-authored-by: Hiroshiba <[email protected]>
Co-authored-by: wappon28dev <[email protected]>

crates/voicevox_core/src/devices.rs

@@ -2,15 +2,45 @@ use serde::{Deserialize, Serialize};
 
 use super::*;
 
+/// このライブラリで利用可能なデバイスの情報。
+///
+/// あくまで本ライブラリが対応しているデバイスの情報であることに注意。GPUが使える環境ではなかったと
+/// しても`cuda`や`dml`は`true`を示しうる。
 #[derive(Getters, Debug, Serialize, Deserialize)]
 pub struct SupportedDevices {
+    /// CPUが利用可能。
+    ///
+    /// 常に`true`。
     cpu: bool,
+    /// CUDAが利用可能。
+    ///
+    /// ONNX Runtimeの[CUDA Execution Provider] (`CUDAExecutionProvider`)に対応する。必要な環境につ
+    /// いてはそちらを参照。
+    ///
+    /// [CUDA Execution Provider]: https://onnxruntime.ai/docs/execution-providers/CUDA-ExecutionProvider.html
     cuda: bool,
+    /// DirectMLが利用可能。
+    ///
+    /// ONNX Runtimeの[DirectML Execution Provider] (`DmlExecutionProvider`)に対応する。必要な環境に
+    /// ついてはそちらを参照。
+    ///
+    /// [DirectML Execution Provider]: https://onnxruntime.ai/docs/execution-providers/DirectML-ExecutionProvider.html
     dml: bool,
 }
 
 impl SupportedDevices {
-    /// サポートされているデバイス情報を取得する
+    /// `SupportedDevices`をコンストラクトする。
+    ///
+    /// # Example
+    ///
+    #[cfg_attr(windows, doc = "```no_run")] // https://github.com/VOICEVOX/voicevox_core/issues/537
+    #[cfg_attr(not(windows), doc = "```")]
+    /// use voicevox_core::SupportedDevices;
+    ///
+    /// let supported_devices = SupportedDevices::create()?;
+    /// #
+    /// # Result::<_, anyhow::Error>::Ok(())
+    /// ```
     pub fn create() -> Result<Self> {
         let mut cuda_support = false;
         let mut dml_support = false;

crates/voicevox_core/src/engine/model.rs

@@ -4,21 +4,33 @@ use serde::{Deserialize, Serialize};
 
 /* 各フィールドのjsonフィールド名はsnake_caseとする*/
 
+/// モーラ（子音＋母音）ごとの情報。
 #[derive(Clone, Debug, new, Getters, Deserialize, Serialize)]
 pub struct MoraModel {
+    /// 文字。
     text: String,
+    /// 子音の音素。
     consonant: Option<String>,
+    /// 子音の音長。
     consonant_length: Option<f32>,
+    /// 母音の音素。
     vowel: String,
+    /// 母音の音長。
     vowel_length: f32,
+    /// 音高。
     pitch: f32,
 }
 
+/// AccentPhrase (アクセント句ごとの情報)。
 #[derive(Clone, Debug, new, Getters, Deserialize, Serialize)]
 pub struct AccentPhraseModel {
+    /// モーラの配列。
     moras: Vec<MoraModel>,
+    /// アクセント箇所。
     accent: usize,
+    /// 後ろに無音を付けるかどうか。
     pause_mora: Option<MoraModel>,
+    /// 疑問系かどうか。
     #[serde(default)]
     is_interrogative: bool,
 }
@@ -33,18 +45,34 @@ impl AccentPhraseModel {
     }
 }
 
+/// AudioQuery (音声合成用のクエリ)。
 #[allow(clippy::too_many_arguments)]
 #[derive(Clone, new, Getters, Deserialize, Serialize)]
 pub struct AudioQueryModel {
+    /// アクセント句の配列。
     accent_phrases: Vec<AccentPhraseModel>,
+    /// 全体の話速。
     speed_scale: f32,
+    /// 全体の音高。
     pitch_scale: f32,
+    /// 全体の抑揚。
     intonation_scale: f32,
+    /// 全体の音量。
     volume_scale: f32,
+    /// 音声の前の無音時間。
     pre_phoneme_length: f32,
+    /// 音声の後の無音時間。
     post_phoneme_length: f32,
+    /// 音声データの出力サンプリングレート。
     output_sampling_rate: u32,
+    /// 音声データをステレオ出力するか否か。
     output_stereo: bool,
+    /// \[読み取り専用\] AquesTalk風記法。
+    ///
+    /// [`Synthesizer::audio_query`]が返すもののみ`Some`となる。入力としてのAudioQueryでは無視され
+    /// る。
+    ///
+    /// [`Synthesizer::audio_query`]: crate::Synthesizer::audio_query
     kana: Option<String>,
 }
 

crates/voicevox_core/src/engine/open_jtalk.rs

@@ -23,6 +23,7 @@ pub enum OpenJtalkError {
 
 pub type Result<T> = std::result::Result<T, OpenJtalkError>;
 
+/// テキスト解析器としてのOpen JTalk。
 pub struct OpenJtalk {
     resources: Mutex<Resources>,
     dict_dir: Option<PathBuf>,
@@ -57,9 +58,10 @@ impl OpenJtalk {
         Ok(s)
     }
 
+    // 先に`load`を呼ぶ必要がある。
     /// ユーザー辞書を設定する。
-    /// 先に [`Self::load`] を呼ぶ必要がある。
-    /// この関数を読んだ後にユーザー辞書を変更した場合は、再度この関数を呼ぶ必要がある。
+    ///
+    /// この関数を呼び出した後にユーザー辞書を変更した場合は、再度この関数を呼ぶ必要がある。
     pub fn use_user_dict(&self, user_dict: &UserDict) -> crate::result::Result<()> {
         let dict_dir = self
             .dict_dir

crates/voicevox_core/src/error.rs

@@ -6,11 +6,7 @@ use std::path::PathBuf;
 use thiserror::Error;
 use uuid::Uuid;
 
-/*
- * 新しいエラーを定義したら、必ずresult_code.rsにあるVoicevoxResultCodeに対応するコードを定義し、
- * internal.rsにある変換関数に変換処理を加えること
- */
-
+/// VOICEVOX COREのエラー。
 #[derive(Error, Debug)]
 pub enum Error {
     /*

crates/voicevox_core/src/lib.rs

@@ -1,3 +1,5 @@
+//! 無料で使える中品質なテキスト読み上げソフトウェア、VOICEVOXのコア。
+
 #![deny(unsafe_code)]
 
 mod devices;

crates/voicevox_core/src/metas.rs

@@ -4,9 +4,17 @@ use super::*;
 use derive_getters::Getters;
 use serde::{Deserialize, Serialize};
 
-/// スタイルIdの実体
+/// [`StyleId`]の実体。
+///
+/// [`StyleId`]: StyleId
 pub type RawStyleId = u32;
-/// スタイルId
+
+/// スタイルID。
+///
+/// VOICEVOXにおける、ある[**話者**(_speaker_)]のある[**スタイル**(_style_)]を指す。
+///
+/// [**話者**(_speaker_)]: SpeakerMeta
+/// [**スタイル**(_style_)]: StyleMeta
 #[derive(PartialEq, Eq, Clone, Copy, Ord, PartialOrd, Deserialize, Serialize, new, Debug)]
 pub struct StyleId(RawStyleId);
 
@@ -22,8 +30,12 @@ impl Display for StyleId {
     }
 }
 
+/// [`StyleVersion`]の実体。
+///
+/// [`StyleVersion`]: StyleVersion
 pub type RawStyleVersion = String;
 
+/// スタイルのバージョン。
 #[derive(PartialEq, Eq, Clone, Ord, PartialOrd, Deserialize, Serialize, new, Debug)]
 pub struct StyleVersion(RawStyleVersion);
 
@@ -39,21 +51,27 @@ impl Display for StyleVersion {
     }
 }
 
-/// 音声モデルのメタ情報
+/// 音声モデルのメタ情報。
 pub type VoiceModelMeta = Vec<SpeakerMeta>;
 
-/// スピーカーのメタ情報
+/// **話者**(_speaker_)のメタ情報。
 #[derive(Deserialize, Serialize, Getters, Clone)]
 pub struct SpeakerMeta {
+    /// 話者名。
     name: String,
+    /// 話者に属するスタイル。
     styles: Vec<StyleMeta>,
+    /// 話者のバージョン。
     version: StyleVersion,
+    /// 話者のUUID。
     speaker_uuid: String,
 }
 
-/// スタイルのメタ情報
+/// **スタイル**(_style_)のメタ情報。
 #[derive(Deserialize, Serialize, Getters, Clone)]
 pub struct StyleMeta {
+    /// スタイルID。
     id: StyleId,
+    /// スタイル名。
     name: String,
 }

crates/voicevox_core/src/result_code.rs

@@ -1,6 +1,6 @@
 use strum::EnumIter;
 
-/// 処理結果を示す結果コード
+/// 処理結果を示す結果コード。
 #[repr(i32)]
 #[derive(Debug, PartialEq, Eq, Clone, Copy, EnumIter)]
 #[allow(non_camel_case_types)]
@@ -29,7 +29,7 @@ pub enum VoicevoxResultCode {
     VOICEVOX_RESULT_EXTRACT_FULL_CONTEXT_LABEL_ERROR = 11,
     /// 無効なutf8文字列が入力された
     VOICEVOX_RESULT_INVALID_UTF8_INPUT_ERROR = 12,
-    /// aquestalk形式のテキストの解析に失敗した
+    /// AquesTalk風記法のテキストの解析に失敗した
     VOICEVOX_RESULT_PARSE_KANA_ERROR = 13,
     /// 無効なAudioQuery
     VOICEVOX_RESULT_INVALID_AUDIO_QUERY_ERROR = 14,
@@ -81,7 +81,7 @@ pub const fn error_result_to_message(result_code: VoicevoxResultCode) -> &'stati
         }
         VOICEVOX_RESULT_INVALID_UTF8_INPUT_ERROR => "入力テキストが無効なUTF-8データでした\0",
         VOICEVOX_RESULT_PARSE_KANA_ERROR => {
-            "入力テキストをAquesTalkライクな読み仮名としてパースすることに失敗しました\0"
+            "入力テキストをAquesTalk風記法としてパースすることに失敗しました\0"
         }
         VOICEVOX_RESULT_INVALID_AUDIO_QUERY_ERROR => "無効なaudio_queryです\0",
         VOICEVOX_RESULT_INVALID_ACCENT_PHRASE_ERROR => "無効なaccent_phraseです\0",

crates/voicevox_core/src/user_dict/dict.rs

@@ -22,6 +22,8 @@ impl UserDict {
 
     /// ユーザー辞書をファイルから読み込む。
     ///
+    /// # Errors
+    ///
     /// ファイルが読めなかった、または内容が不正だった場合はエラーを返す。
     pub fn load(&mut self, store_path: &str) -> Result<()> {
         let store_path = std::path::Path::new(store_path);

crates/voicevox_core/src/user_dict/part_of_speech_data.rs

@@ -4,29 +4,29 @@ use std::collections::HashMap;
 
 use crate::UserDictWordType;
 
-/// 最小の優先度
+/// 最小の優先度。
 pub static MIN_PRIORITY: u32 = 0;
-/// 最大の優先度
+/// 最大の優先度。
 pub static MAX_PRIORITY: u32 = 10;
 
-/// 品詞ごとの情報
+/// 品詞ごとの情報。
 #[derive(Debug, Getters)]
 pub struct PartOfSpeechDetail {
-    /// 品詞
+    /// 品詞。
     pub part_of_speech: &'static str,
-    /// 品詞細分類1
+    /// 品詞細分類1。
     pub part_of_speech_detail_1: &'static str,
-    /// 品詞細分類2
+    /// 品詞細分類2。
     pub part_of_speech_detail_2: &'static str,
-    /// 品詞細分類3
+    /// 品詞細分類3。
     pub part_of_speech_detail_3: &'static str,
-    /// 文脈IDは辞書の左・右文脈IDのこと
+    /// 文脈IDは辞書の左・右文脈IDのこと。
     ///
     /// 参考: <https://github.com/VOICEVOX/open_jtalk/blob/427cfd761b78efb6094bea3c5bb8c968f0d711ab/src/mecab-naist-jdic/_left-id.def>
     pub context_id: i32,
-    /// コストのパーセンタイル
+    /// コストのパーセンタイル。
     pub cost_candidates: Vec<i32>,
-    /// アクセント結合規則の一覧
+    /// アクセント結合規則の一覧。
     pub accent_associative_rules: Vec<&'static str>,
 }
 

crates/voicevox_core/src/voice_model.rs

@@ -9,20 +9,26 @@ use std::{
     path::{Path, PathBuf},
 };
 
-/// 音声モデルIdの実体
+/// [`VoiceModelId`]の実体。
+///
+/// [`VoiceModelId`]: VoiceModelId
 pub type RawVoiceModelId = String;
 
-/// 音声モデルId (型を強く分けるためにこうしている)
+/// 音声モデルID。
 #[derive(PartialEq, Eq, Clone, Ord, PartialOrd, Deserialize, new, Getters, Debug)]
 pub struct VoiceModelId {
     raw_voice_model_id: RawVoiceModelId,
 }
 
-/// 音声モデル
+/// 音声モデル。
+///
+/// VVMファイルと対応する。
 #[derive(Getters, Clone)]
 pub struct VoiceModel {
+    /// ID。
     id: VoiceModelId,
     manifest: Manifest,
+    /// メタ情報。
     metas: VoiceModelMeta,
     path: PathBuf,
 }
@@ -51,7 +57,7 @@ impl VoiceModel {
             decode_model: decode_model_result?,
         })
     }
-    /// 与えられたパスからモデルを取得する
+    /// VVMファイルから`VoiceModel`をコンストラクトする。
     pub async fn from_path(path: impl AsRef<Path>) -> Result<Self> {
         let reader = VvmEntryReader::open(&path).await?;
         let manifest = reader.read_vvm_json::<Manifest>("manifest.json").await?;