...

docs/C-API/introduction.md

@@ -7,6 +7,32 @@ order: 10
 All public functions in the C API are prefixed with `py_` in [pocketpy.h](https://github.com/pocketpy/pocketpy/blob/main/include/pocketpy/pocketpy.h).
 
 
+## Overview
+
+pocketpy works with opaque references. `py_Ref` is used to reference objects in the virtual machine. It is your responsibility to ensure a reference is valid before using it. See following reference types:
+
+```c
+/// A generic reference to a python object.
+typedef py_TValue* py_Ref;
+/// A reference which has the same lifespan as the python object.
+typedef py_TValue* py_ObjectRef;
+/// A global reference which has the same lifespan as the VM.
+typedef py_TValue* py_GlobalRef;
+/// A specific location in the value stack of the VM.
+typedef py_TValue* py_StackRef;
+/// An item reference to a container object. It invalidates when the container is modified.
+typedef py_TValue* py_ItemRef;
+/// An output reference for returning a value.
+typedef py_TValue* py_OutRef;
+```
+
+You can store python objects into "stack" or "register".
+We provide 8 registers and you can get references to them by `py_reg()`.
+Also, `py_retval()` is a special register that is used to store the return value of a `py_CFunction`.
+Registers are shared so they could be overwritten easily.
+If you want to store python objects across function calls, you should store them into the stack via `py_push()` and `py_pop()`.
+
+
 ### `PY_RAISE` macro
 
 Mark a function that can raise an exception on failure.