docs: [Python, Java] 各アイテムにPydanticとGSONの廃止案内を載せる (#985)

脱Pydanticと脱GSONをやるのはv0.17であることを前提にし、ちょっと弱めの表現にしてある。 Resolves: #963 Refs: #960, #984
VOICEVOX · Feb 8, 2025 · 00bdcdc · 00bdcdc
1 parent a952898
commit 00bdcdc
Show file tree

Hide file tree

Showing 8 changed files with 110 additions and 11 deletions.
diff --git a/crates/voicevox_core_java_api/lib/src/main/java/jp/hiroshiba/voicevoxcore/AccentPhrase.java b/crates/voicevox_core_java_api/lib/src/main/java/jp/hiroshiba/voicevoxcore/AccentPhrase.java
@@ -7,7 +7,12 @@
 import java.util.ArrayList;
 import java.util.List;
 
-/** AccentPhrase (アクセント句ごとの情報)。 */
+/**
+ * AccentPhrase (アクセント句ごとの情報)。
+ *
+ * <p>現在この型はGSONに対応しているが、将来的には <a href="https://github.com/VOICEVOX/voicevox_core/issues/984"
+ * target="_blank">Jacksonに切り替わる予定</a> 。
+ */
 public class AccentPhrase {
   /** モーラの配列。 */
   @SerializedName("moras")

diff --git a/crates/voicevox_core_java_api/lib/src/main/java/jp/hiroshiba/voicevoxcore/AudioQuery.java b/crates/voicevox_core_java_api/lib/src/main/java/jp/hiroshiba/voicevoxcore/AudioQuery.java
@@ -7,7 +7,12 @@
 import java.util.ArrayList;
 import java.util.List;
 
-/** AudioQuery（音声合成用のクエリ）。 */
+/**
+ * AudioQuery（音声合成用のクエリ）。
+ *
+ * <p>現在この型はGSONに対応しているが、将来的には <a href="https://github.com/VOICEVOX/voicevox_core/issues/984"
+ * target="_blank">Jacksonに切り替わる予定</a> 。
+ */
 public class AudioQuery {
   /** アクセント句の配列。 */
   @SerializedName("accent_phrases")

diff --git a/crates/voicevox_core_java_api/lib/src/main/java/jp/hiroshiba/voicevoxcore/CharacterMeta.java b/crates/voicevox_core_java_api/lib/src/main/java/jp/hiroshiba/voicevoxcore/CharacterMeta.java
@@ -5,7 +5,12 @@
 import jakarta.annotation.Nonnull;
 import jakarta.annotation.Nullable;
 
-/** キャラクターのメタ情報。 */
+/**
+ * キャラクターのメタ情報。
+ *
+ * <p>現在この型はGSONに対応しているが、将来的には <a href="https://github.com/VOICEVOX/voicevox_core/issues/984"
+ * target="_blank">Jacksonに切り替わる予定</a> 。
+ */
 public class CharacterMeta {
   /** キャラクター名。 */
   @SerializedName("name")

diff --git a/crates/voicevox_core_java_api/lib/src/main/java/jp/hiroshiba/voicevoxcore/GlobalInfo.java b/crates/voicevox_core_java_api/lib/src/main/java/jp/hiroshiba/voicevoxcore/GlobalInfo.java
@@ -35,6 +35,9 @@ public static String getVersion() {
    * <p>あくまでONNX Runtimeが対応しているデバイスの情報であることに注意。GPUが使える環境ではなかったとしても {@link #cuda} や {@link #dml} は
    * {@code true} を示しうる。
    *
+   * <p>現在この型はGSONに対応しているが、将来的には <a href="https://github.com/VOICEVOX/voicevox_core/issues/984"
+   * target="_blank">Jacksonに切り替わる予定</a> 。
+   *
    * <p>{@code Gson#fromJson} でJSONから変換することはできない。その試みは {@link UnsupportedOperationException} となる。
    */
   public static class SupportedDevices {

diff --git a/crates/voicevox_core_java_api/lib/src/main/java/jp/hiroshiba/voicevoxcore/Mora.java b/crates/voicevox_core_java_api/lib/src/main/java/jp/hiroshiba/voicevoxcore/Mora.java
@@ -5,7 +5,12 @@
 import jakarta.annotation.Nonnull;
 import jakarta.annotation.Nullable;
 
-/** モーラ（子音＋母音）ごとの情報。 */
+/**
+ * モーラ（子音＋母音）ごとの情報。
+ *
+ * <p>現在この型はGSONに対応しているが、将来的には <a href="https://github.com/VOICEVOX/voicevox_core/issues/984"
+ * target="_blank">Jacksonに切り替わる予定</a> 。
+ */
 public class Mora {
   /** 文字。 */
   @SerializedName("text")

diff --git a/crates/voicevox_core_java_api/lib/src/main/java/jp/hiroshiba/voicevoxcore/StyleMeta.java b/crates/voicevox_core_java_api/lib/src/main/java/jp/hiroshiba/voicevoxcore/StyleMeta.java
@@ -5,7 +5,12 @@
 import jakarta.annotation.Nonnull;
 import jakarta.annotation.Nullable;
 
-/** スタイル（style）のメタ情報。 */
+/**
+ * スタイル（style）のメタ情報。
+ *
+ * <p>現在この型はGSONに対応しているが、将来的には <a href="https://github.com/VOICEVOX/voicevox_core/issues/984"
+ * target="_blank">Jacksonに切り替わる予定</a> 。
+ */
 public class StyleMeta {
   /** スタイル名。 */
   @SerializedName("name")

diff --git a/crates/voicevox_core_java_api/lib/src/main/java/jp/hiroshiba/voicevoxcore/UserDictWord.java b/crates/voicevox_core_java_api/lib/src/main/java/jp/hiroshiba/voicevoxcore/UserDictWord.java
@@ -13,7 +13,12 @@
 import jakarta.validation.constraints.Max;
 import jakarta.validation.constraints.Min;
 
-/** ユーザー辞書の単語。 */
+/**
+ * ユーザー辞書の単語。
+ *
+ * <p>現在この型はGSONに対応しているが、将来的には <a href="https://github.com/VOICEVOX/voicevox_core/issues/984"
+ * target="_blank">Jacksonに切り替わる予定</a> 。
+ */
 public class UserDictWord {
   /** 単語の表層形。 */
   @SerializedName("surface")

diff --git a/crates/voicevox_core_python_api/python/voicevox_core/_models/__init__.py b/crates/voicevox_core_python_api/python/voicevox_core/_models/__init__.py
@@ -89,7 +89,17 @@ def _(style_type: StyleType):
 
 @pydantic.dataclasses.dataclass
 class StyleMeta:
-    """**スタイル** (_style_)のメタ情報。"""
+    """
+    **スタイル** (_style_)のメタ情報。
+
+    現在は |pydantic-dataclasses-dataclass-stylemeta|_ ではあるが、将来的には
+    |de-pydantic-stylemeta|_ 。
+
+    .. |pydantic-dataclasses-dataclass-stylemeta| replace:: ``@pydantic.dataclasses.dataclass``
+    .. _pydantic-dataclasses-dataclass-stylemeta: https://docs.pydantic.dev/2.10/concepts/dataclasses/
+    .. |de-pydantic-stylemeta| replace:: JSONと相互変換するメソッドのみ付いた、素の ``dataclass`` になる予定
+    .. _de-pydantic-stylemeta: https://github.com/VOICEVOX/voicevox_core/issues/960#issuecomment-2629424401
+    """
 
     name: str
     """スタイル名。"""
@@ -110,7 +120,17 @@ class StyleMeta:
 
 @pydantic.dataclasses.dataclass
 class CharacterMeta:
-    """**キャラクター**のメタ情報。"""
+    """
+    **キャラクター**のメタ情報。
+
+    現在は |pydantic-dataclasses-dataclass-charactermeta|_ ではあるが、将来的には
+    |de-pydantic-charactermeta|_ 。
+
+    .. |pydantic-dataclasses-dataclass-charactermeta| replace:: ``@pydantic.dataclasses.dataclass``
+    .. _pydantic-dataclasses-dataclass-charactermeta: https://docs.pydantic.dev/2.10/concepts/dataclasses/
+    .. |de-pydantic-charactermeta| replace:: JSONと相互変換するメソッドのみ付いた、素の ``dataclass`` になる予定
+    .. _de-pydantic-charactermeta: https://github.com/VOICEVOX/voicevox_core/issues/960#issuecomment-2629424401
+    """
 
     name: str
     """キャラクター名。"""
@@ -142,6 +162,14 @@ class SupportedDevices:
 
     JSONからの変換も含め、VOICEVOX CORE以外が作ることはできない。作ろうとした場合
     ``TypeError`` となる。
+
+    現在は |pydantic-dataclasses-dataclass-supporteddevices|_ ではあるが、将来的には
+    |de-pydantic-supporteddevices|_ 。
+
+    .. |pydantic-dataclasses-dataclass-supporteddevices| replace:: ``@pydantic.dataclasses.dataclass``
+    .. _pydantic-dataclasses-dataclass-supporteddevices: https://docs.pydantic.dev/2.10/concepts/dataclasses/
+    .. |de-pydantic-supporteddevices| replace:: JSONと相互変換するメソッドのみ付いた、素の ``dataclass`` になる予定
+    .. _de-pydantic-supporteddevices: https://github.com/VOICEVOX/voicevox_core/issues/960#issuecomment-2629424401
     """
 
     cpu: bool
@@ -222,7 +250,17 @@ def _(mode: AccelerationMode):
 
 @pydantic.dataclasses.dataclass
 class Mora:
-    """モーラ（子音＋母音）ごとの情報。"""
+    """
+    モーラ（子音＋母音）ごとの情報。
+
+    現在は |pydantic-dataclasses-dataclass-mora|_ ではあるが、将来的には
+    |de-pydantic-mora|_ 。
+
+    .. |pydantic-dataclasses-dataclass-mora| replace:: ``@pydantic.dataclasses.dataclass``
+    .. _pydantic-dataclasses-dataclass-mora: https://docs.pydantic.dev/2.10/concepts/dataclasses/
+    .. |de-pydantic-mora| replace:: JSONと相互変換するメソッドのみ付いた、素の ``dataclass`` になる予定
+    .. _de-pydantic-mora: https://github.com/VOICEVOX/voicevox_core/issues/960#issuecomment-2629424401
+    """
 
     text: str
     """文字。"""
@@ -245,7 +283,17 @@ class Mora:
 
 @pydantic.dataclasses.dataclass
 class AccentPhrase:
-    """AccentPhrase (アクセント句ごとの情報)。"""
+    """
+    AccentPhrase (アクセント句ごとの情報)。
+
+    現在は |pydantic-dataclasses-dataclass-accentphrase|_ ではあるが、将来的には
+    |de-pydantic-accentphrase|_ 。
+
+    .. |pydantic-dataclasses-dataclass-accentphrase| replace:: ``@pydantic.dataclasses.dataclass``
+    .. _pydantic-dataclasses-dataclass-accentphrase: https://docs.pydantic.dev/2.10/concepts/dataclasses/
+    .. |de-pydantic-accentphrase| replace:: JSONと相互変換するメソッドのみ付いた、素の ``dataclass`` になる予定
+    .. _de-pydantic-accentphrase: https://github.com/VOICEVOX/voicevox_core/issues/960#issuecomment-2629424401
+    """
 
     moras: list[Mora]
     """モーラの配列。"""
@@ -275,6 +323,14 @@ class AudioQuery:
     """
     AudioQuery (音声合成用のクエリ)。
 
+    現在は |pydantic-dataclasses-dataclass-audioquery|_ ではあるが、将来的には
+    |de-pydantic-audioquery|_ 。
+
+    .. |pydantic-dataclasses-dataclass-audioquery| replace:: ``@pydantic.dataclasses.dataclass``
+    .. _pydantic-dataclasses-dataclass-audioquery: https://docs.pydantic.dev/2.10/concepts/dataclasses/
+    .. |de-pydantic-audioquery| replace:: JSONと相互変換するメソッドのみ付いた、素の ``dataclass`` になる予定
+    .. _de-pydantic-audioquery: https://github.com/VOICEVOX/voicevox_core/issues/960#issuecomment-2629424401
+
     JSONへの変換は ``pydantic.TypeAdapter.dump_json`` を用いなければならない。また、
     ``dump_json`` や ``json_schema`` を用いるときは ``by_alias=True``
     を指定しなければならない。
@@ -391,7 +447,17 @@ def _(word_type: UserDictWordType):
 
 @pydantic.dataclasses.dataclass
 class UserDictWord:
-    """ユーザー辞書の単語。"""
+    """
+    ユーザー辞書の単語。
+
+    現在は |pydantic-dataclasses-dataclass-userdictword|_ ではあるが、将来的には
+    |de-pydantic-userdictword|_ 。
+
+    .. |pydantic-dataclasses-dataclass-userdictword| replace:: ``@pydantic.dataclasses.dataclass``
+    .. _pydantic-dataclasses-dataclass-userdictword: https://docs.pydantic.dev/2.10/concepts/dataclasses/
+    .. |de-pydantic-userdictword| replace:: JSONと相互変換するメソッドのみ付いた、素の ``dataclass`` になる予定
+    .. _de-pydantic-userdictword: https://github.com/VOICEVOX/voicevox_core/issues/960#issuecomment-2629424401
+    """
 
     surface: str
     """言葉の表層形。"""