From ed631cdf8765eb02bc46c5a1000d879e9fac6d52 Mon Sep 17 00:00:00 2001
From: Christof Petig <christof.petig@arcor.de>
Date: Fri, 31 May 2024 17:33:36 +0200
Subject: [PATCH] more extensive type documentation

---
 crates/cpp/helper-types/wit-common.h |  6 +-----
 crates/cpp/helper-types/wit-guest.h  | 15 +++++++++++++++
 crates/cpp/helper-types/wit-host.h   |  8 +++++++-
 3 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/crates/cpp/helper-types/wit-common.h b/crates/cpp/helper-types/wit-common.h
index 225f57755..c8316ba62 100644
--- a/crates/cpp/helper-types/wit-common.h
+++ b/crates/cpp/helper-types/wit-common.h
@@ -13,7 +13,7 @@ namespace wit {
 #if __cplusplus > 202001L
 using std::span;
 #else
-// minimal implementation to get things going
+/// Minimal span (vector view) implementation for older C++ environments
 template <class T> class span {
   T const *address;
   size_t length;
@@ -32,8 +32,4 @@ template <class T> class span {
   span(std::vector<U> const&vec) : address(vec.data()), length(vec.size()) {}
 };
 #endif
-
-template <typename T> struct Owned {
-  T *ptr;
-};
 } // namespace wit
diff --git a/crates/cpp/helper-types/wit-guest.h b/crates/cpp/helper-types/wit-guest.h
index 745b268df..699d3cb9e 100644
--- a/crates/cpp/helper-types/wit-guest.h
+++ b/crates/cpp/helper-types/wit-guest.h
@@ -6,6 +6,10 @@
 #include "wit-common.h"
 
 namespace wit {
+/// A string in linear memory, freed unconditionally using free
+///
+/// A normal C++ string makes no guarantees about where the characters
+/// are stored and how this is freed.
 class string {
   uint8_t const *data_;
   size_t length;
@@ -43,6 +47,10 @@ class string {
   }
 };
 
+/// A vector in linear memory, freed unconditionally using free
+///
+/// You can't detach the data memory from a vector, nor create one
+/// in a portable way from a buffer and lenght without copying.
 template <class T>
 class vector {
   T *data_;
@@ -81,6 +89,10 @@ class vector {
   }
 };
 
+/// @brief  A Resource defined within the guest (guest side)
+/// 
+/// It registers with the host and should remain in a static location.
+/// Typically referenced by the Owned type
 template <class R> class ResourceExportBase {
   public:
     struct Deleter {
@@ -102,6 +114,9 @@ template <class R> class ResourceExportBase {
     int32_t into_handle() { int32_t result = handle; handle=invalid; return result; }
 };
 
+/// @brief A Resource imported from the host (guest side)
+///
+/// Wraps the identifier and can be forwarded but not duplicated
 class ResourceImportBase {
 public:
   static const int32_t invalid = -1;
diff --git a/crates/cpp/helper-types/wit-host.h b/crates/cpp/helper-types/wit-host.h
index 11dcfb56e..df435e269 100644
--- a/crates/cpp/helper-types/wit-host.h
+++ b/crates/cpp/helper-types/wit-host.h
@@ -43,6 +43,7 @@ typedef guest_address (*guest_alloc_t)(WASMExecEnv *, guest_size size,
                                        guest_size align);
 #endif
 
+/// A string in linear memory (host-side handle)
 // host code never de-allocates directly
 class string {
   guest_address data_;
@@ -102,6 +103,7 @@ class string {
 #endif
 };
 
+/// A vector in linear memory (host-side handle)
 template <class T>
 class vector {
   guest_address data_;
@@ -124,6 +126,7 @@ class vector {
   guest_size size() const { return length; }
 };
 
+/// Wrapper for specialized de-allocation of a returned type (calling cabi_post_*)
 template <class T> class guest_owned : public T {
   guest_address data_;
 #ifdef WIT_HOST_WAMR
@@ -183,6 +186,8 @@ template <class T> class guest_owned : public T {
 #endif
 };
 
+/// @brief Helper class to map between IDs and resources
+/// @tparam R Type of the Resource
 template <class R> class ResourceTable {
   static std::map<int32_t, R> resources;
 
@@ -208,7 +213,7 @@ template <class R> class ResourceTable {
   }
 };
 
-// guest exported resource
+/// Guest exported resource (host side handle)
 class ResourceExportBase : public ResourceTable<guest_address> {
   protected:
     guest_address rep;
@@ -230,6 +235,7 @@ class ResourceExportBase : public ResourceTable<guest_address> {
     guest_address take_rep() { guest_address res = rep; rep=0; return res; }
 };
 
+/// Host defined resource (host side definition)
 template <class R>
 class ResourceImportBase : public ResourceTable<R*> {
     int32_t index;