add a comment explaining the API and a limitation of the current impl…

…ementation

hpy/debug/src/include/hpy_debug.h

@@ -3,7 +3,28 @@
 
 #include "hpy.h"
 
-HPyContext hpy_debug_get_ctx(HPyContext original_ctx);
+/*
+  This is the main public API for the debug mode, and it's meant to be used
+  by hpy.universal implementations (including but not limited to the
+  CPython's version of hpy.universal which is included in this repo).
+
+  The idea is that for every uctx there is a corresponding unique dctx which
+  wraps it.
+
+  If you call hpy_debug_get_ctx twice on the same uctx, you get the same
+  result.
+
+  IMPLEMENTATION NOTE: at the moment of writing, the only knonw user of the
+  debug mode is CPython's hpy.universal: in that module, the uctx is a
+  statically allocated singleton, so for simplicity of implementation
+  currently we do the same inside debug_ctx.c, with a sanity check to ensure
+  that we don't call hpy_debug_get_ctx with different uctxs. But this is a
+  limitation of the current implementation and users should not rely on it. It
+  is likely that we will need to change it in the future, e.g. if we want to
+  have per-subinterpreter uctxs.
+*/
+
+HPyContext hpy_debug_get_ctx(HPyContext uctx);
 
 // this is the HPy init function created by HPy_MODINIT. In CPython's version
 // of hpy.universal the code is embedded inside the extension, so we can call