diff --git a/docs/C-API/introduction.md b/docs/C-API/introduction.md
index faf16380..c4f43ca5 100644
--- a/docs/C-API/introduction.md
+++ b/docs/C-API/introduction.md
@@ -4,4 +4,16 @@ icon: dot
 order: 10
 ---
 
-TBA
\ No newline at end of file
+TBA
+
+
+### `PY_RAISE` macro
+
+Mark a function that can raise an exception on failure.
+
++ If the function returns `bool`, then `false` means an exception is raised.
++ If the function returns `int`, then `-1` means an exception is raised.
+
+### `PY_RETURN` macro
+
+Mark a function that can store a value in `py_retval()` on success.
\ No newline at end of file
diff --git a/include/pocketpy/pocketpy.h b/include/pocketpy/pocketpy.h
index e661330a..a6e7d8c6 100644
--- a/include/pocketpy/pocketpy.h
+++ b/include/pocketpy/pocketpy.h
@@ -34,11 +34,7 @@ typedef struct c11_sv {
     int size;
 } c11_sv;
 
-/// Mark a function that can raise an exception.
-/// + If the function returns `bool`, then `false` means an exception is raised.
-/// + If the function returns `int`, then `-1` means an exception is raised.
 #define PY_RAISE
-/// Mark a function that returns a value by `py_retval()` on success.
 #define PY_RETURN
 
 /// A generic reference to a python object.
diff --git a/scripts/gen_docs.py b/scripts/gen_docs.py
index aba10635..2336c8ad 100644
--- a/scripts/gen_docs.py
+++ b/scripts/gen_docs.py
@@ -19,9 +19,9 @@ class Function:
     def badges(self):
         res = []
         if self.is_py_raise:
-            res.append('[!badge text="raise" variant="danger"]')
+            res.append('[!badge text="raise" variant="danger"](../introduction/#py_raise-macro)')
         if self.is_py_return:
-            res.append('[!badge text="return"]')
+            res.append('[!badge text="return"](../introduction/#py_return-macro)')
         return ' '.join(res)
 
     def markdown(self):