runtime: add comments/docs explaining the semantics of IA2_{CON,DE}STRUCTOR

Author: kkysen

runtime/libia2/include/ia2.h

@@ -47,15 +47,23 @@
 #define IA2_POST_CONDITION_FOR(target_func) __attribute__((annotate("ia2_post_condition:" #target_func)))
 
 /// Mark the annotated function as a constructor for the type `T`,
-/// where the function has the signature `R f(T*, ...)`.
+/// where the function has the signature `R f(T* this, ...)`.
 /// The `...` aren't varargs here; it just means that
 /// there can be any number of extra args after the `T*`.
 ///
+/// This function should initialize the `T*`
+/// and marks the start of its lifetime as a
+/// registered and valid ptr of type `T`.
+///
 /// Note that this is not the same as `__attribute__((constructor))`.
 #define IA2_CONSTRUCTOR __attribute__((annotate("ia2_constructor")))
 
 /// Mark the annotated function as a destructor for the type `T`,
-/// where the function has the signature `void f(T*)`.
+/// where the function has the signature `void f(T* this)`.
+///
+/// This function should unitialize the `T*`
+/// and marks the end of its lifetime as a
+/// registered and valid ptr of type `T`.
 ///
 /// Note that this is not the same as `__attribute__((destructor))`.
 #define IA2_DESTRUCTOR __attribute__((annotate("ia2_destructor")))

tests/type_confusion/dav1d.c

@@ -8,13 +8,13 @@ RUN: cat dav1d_call_gates_1.ld | FileCheck --check-prefix=LINKARGS %s
 #define IA2_COMPARTMENT 2
 #include <ia2_compartment_init.inc>
 
-IA2_CONSTRUCTOR
+IA2_CONSTRUCTOR // Registers that ptr `this` has type `Dav1dContext` now.
 int dav1d_open(Dav1dContext *const this, const Dav1dSettings *const s) {
   // Initialize `this`; implementation omitted.
   return 0;
 }
 
-IA2_DESTRUCTOR
+IA2_DESTRUCTOR // Registers that ptr `this` no longer has type `Dav1dContext`.
 void dav1d_close(Dav1dContext *const this) {
   // Uninitialize `this`; implementation omitted.
 }