From a04d57f526fe04e034e7d52aa40fc7d3ed4a0a35 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=A9gis=20Behmo?= <regis@behmo.com>
Date: Mon, 22 Jan 2024 13:04:30 +0100
Subject: [PATCH] docs: extra hooks functions and utilities

---
 docs/reference/api/hooks/index.rst | 23 ++++++++++++++++++++---
 tutor/core/hooks/priorities.py     |  4 ++++
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/docs/reference/api/hooks/index.rst b/docs/reference/api/hooks/index.rst
index d668685..8a5700e 100644
--- a/docs/reference/api/hooks/index.rst
+++ b/docs/reference/api/hooks/index.rst
@@ -1,8 +1,11 @@
 .. _hooks_api:
 
-==========
-Hook types
-==========
+=========
+Hooks API
+=========
+
+Types
+=====
 
 This is the Python documentation of the two types of hooks (actions and filters) as well as the contexts system which is used to instrument them. Understanding how Tutor hooks work is useful to create plugins that modify the behaviour of Tutor. However, plugin developers should almost certainly not import these hook types directly. Instead, use the reference :ref:`hooks catalog <hooks_catalog>`.
 
@@ -12,3 +15,17 @@ This is the Python documentation of the two types of hooks (actions and filters)
    actions
    filters
    contexts
+
+Utilities
+=========
+
+Functions
+---------
+
+.. autofunction:: tutor.core.hooks::clear_all
+
+Priorities
+----------
+
+.. automodule:: tutor.core.hooks.priorities
+   :members: HIGH, DEFAULT, LOW
diff --git a/tutor/core/hooks/priorities.py b/tutor/core/hooks/priorities.py
index 616debc..ca2b6f5 100644
--- a/tutor/core/hooks/priorities.py
+++ b/tutor/core/hooks/priorities.py
@@ -4,8 +4,12 @@ import typing as t
 
 from typing_extensions import Protocol
 
+#: High priority callbacks are triggered first.
 HIGH = 5
+#: By default, all callbacks have the same priority and are processed in the order they
+#: were added.
 DEFAULT = 10
+#: Low-priority callbacks are called last. Add callbacks with this priority to override previous callbacks. To add callbacks with even lower priority, use ``LOW + somevalue`` (though such behaviour is not encouraged).
 LOW = 50