From b4604873c49a29a70cf503e7552a567b525fe2b2 Mon Sep 17 00:00:00 2001
From: ANH <abd.nh25@gmail.com>
Date: Fri, 31 Jul 2020 03:06:13 +0300
Subject: [PATCH] document hooks

---
 qt/aqt/gui_hooks.py      | 24 ++++++++++++++++++++++++
 qt/tools/genhooks_gui.py | 22 ++++++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/qt/aqt/gui_hooks.py b/qt/aqt/gui_hooks.py
index 8c8ec5fd9..8fd74230a 100644
--- a/qt/aqt/gui_hooks.py
+++ b/qt/aqt/gui_hooks.py
@@ -2113,6 +2113,18 @@ reviewer_will_end = _ReviewerWillEndHook()
 
 
 class _ReviewerWillPlayAnswerSoundsHook:
+    """Called before showing the answer/back side.
+
+        `tags` can be used to inspect and manipulate the sounds
+        that will be played (if any).
+
+        This won't be called when the user manually plays sounds
+        using `Replay Audio`.
+
+        Not that this hook is called even when the `Automatically play audio`
+        option is unchecked; This is so as to allow playing custom
+        sounds regardless of that option."""
+
     _hooks: List[Callable[[Card, "List[anki.sound.AVTag]"], None]] = []
 
     def append(self, cb: Callable[[Card, "List[anki.sound.AVTag]"], None]) -> None:
@@ -2140,6 +2152,18 @@ reviewer_will_play_answer_sounds = _ReviewerWillPlayAnswerSoundsHook()
 
 
 class _ReviewerWillPlayQuestionSoundsHook:
+    """Called before showing the question/front side.
+
+        `tags` can be used to inspect and manipulate the sounds
+        that will be played (if any).
+
+        This won't be called when the user manually plays sounds
+        using `Replay Audio`.
+
+        Not that this hook is called even when the `Automatically play audio`
+        option is unchecked; This is so as to allow playing custom
+        sounds regardless of that option."""
+
     _hooks: List[Callable[[Card, "List[anki.sound.AVTag]"], None]] = []
 
     def append(self, cb: Callable[[Card, "List[anki.sound.AVTag]"], None]) -> None:
diff --git a/qt/tools/genhooks_gui.py b/qt/tools/genhooks_gui.py
index ea7fe384a..2fc9d5024 100644
--- a/qt/tools/genhooks_gui.py
+++ b/qt/tools/genhooks_gui.py
@@ -93,10 +93,32 @@ hooks = [
     Hook(
         name="reviewer_will_play_question_sounds",
         args=["card: Card", "tags: List[anki.sound.AVTag]"],
+        doc="""Called before showing the question/front side.
+
+        `tags` can be used to inspect and manipulate the sounds
+        that will be played (if any).
+
+        This won't be called when the user manually plays sounds
+        using `Replay Audio`.
+
+        Not that this hook is called even when the `Automatically play audio`
+        option is unchecked; This is so as to allow playing custom
+        sounds regardless of that option.""",
     ),
     Hook(
         name="reviewer_will_play_answer_sounds",
         args=["card: Card", "tags: List[anki.sound.AVTag]"],
+        doc="""Called before showing the answer/back side.
+
+        `tags` can be used to inspect and manipulate the sounds
+        that will be played (if any).
+
+        This won't be called when the user manually plays sounds
+        using `Replay Audio`.
+
+        Not that this hook is called even when the `Automatically play audio`
+        option is unchecked; This is so as to allow playing custom
+        sounds regardless of that option.""",
     ),
     # Debug
     ###################