...

docs/C-API/introduction.md

@@ -5,3 +5,15 @@ order: 10
 ---
 
 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.

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.

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):