more elaborate explanation

crates/cpp/DESIGN.md

@@ -16,29 +16,39 @@
 | t | owernership transferred |
 | p | cabi_post_ cleans up |
 
+| API | | | ABI | |
+| --- | --- | --- | --- | --- |
+| 🕸 | old | | 📘 | canonical |
+| 💎 | new | | 🪞 | symmetric |
+
 | Code | mode | WIT Type | Rust type | C++ Type | Lower | Reason |
 | --- | --- | --- | --- | --- | --- | --- |
 | GIA | v | string | &str[^1] | string_view (17) | addr, len | |
 | | | list | &[T] | wit::span [^5] | addr, len | |
 | | | tuple | (...) | std::tuple | 0, 1, ...| |
-| | | tuple<string, list> | (&str, &[T]) | std::tuple<...> | a,l,a,l | 
-| | | record{string, list} | &T | T const& | a,l,a,l | 
+| | | tuple<string, list> | (&str, &[T]) | std::tuple<...> | a,l,a,l |
+| | | record{string, list} | &T | T const& | a,l,a,l |
 | | | large-struct (>16 args) | &T | T const& | &t |
 | | | result<string,list> | Result<&str, &[]> | std::expected<string_view, span> | d,a,l |
 | | | option\<string> | Option\<&str> | optional<string_view> const& | d,a,l|
 | | | list\<resrc> | &[\&Resrc]? | vector<string_view> const& | a,l|
-| GIR | t | string | String | wit::string[^2] | &(addr, len) | |
+| GIR | t | string | String | wit::string[^2] | &(addr, len) [^8] | |
 | | | list | Vec | wit::vector | &(a,l) |
 | | | result<string,list> | Result<String, Vec> | std::expected<wit::string, wit::vector> | &(d,a,l) |
-| GEA | t | string | String | wit::string&& | addr, len |
-| | | result<string,list> | Result<String, Vec> | std::expected<wit::string, wit::vector>&& | d,a,l |
-| GER | p | string | String | wit::string (or std?) | -> &(a,l) cabi_post_N:P/I#F |
-| | | result<string,list> | Result<String, Vec> | std::expected<wit::string, wit::vector> | -> &(d,a,l) cabi_post |
+| GEA | t | string | String | 🕸 wit::string&& | addr, len |
+| | | | | 💎 string_view | |
+| | | result<string,list> | Result<String, Vec> | 🕸 std::expected<wit::string, wit::vector>&& | d,a,l |
+| | | | | 💎 std::expected<string_view, wit::span> | |
+| GER | p | string | String | wit::string (or std?) | 📘 -> &(a,l) cabi_post_N:P/I#F [^7] |
+| | | | | | 🪞 &(a,l) |
+| | | result<string,list> | Result<String, Vec> | std::expected<wit::string, wit::vector> | 📘 -> &(d,a,l) cabi_post |
 | --S | ? | string | String | wit::string | addr, len |
 | HIA | v | string | | string_view | a,l |
 | HIR | t | string | | wit::string[^3] | &(a,l) |
-| HEA | t | string | | wit::string[^4] | a,l | 
-| HER | p | string | | wit::guest_owned<string_view> | -> &(a,l) |
+| HEA | t | string | | 🕸 wit::string[^4] | a,l |
+| | | | | 💎 string_view [^6] | |
+| HER | p | string | | 🕸 wit::guest_owned<string_view> | 📘 -> &(a,l) |
+| | | | | 💎 wit::string [^6] | 🪞 &(a,l) |
 
 [^1]: The host never frees memory (is never passed ownership)!
 
@@ -52,31 +62,37 @@ Complex (non-POD) struct elements on the host will need exec_env to decode or co
 
 [^5]: std::span requires C++-20, this alias should give minimal functionality with older compiler targets.
 
-# Symmetric ABI
+[^6]: Not implemented, for now symmetric is priority
+
+[^7]: Here the callee (guest) allocates the memory for the set on its side
+
+[^8]: Caller passes address of the return object as argument
+
+## [Symmetric ABI](https://github.com/WebAssembly/component-model/issues/386)
 
 The idea is to directly connect (link) components to each other.
 
 Thus imported and exported functions and resources need to be compatible
 at the ABI level.
 
-For now for functions the following convention is used in both directions:
+For now for functions the guest import convention is used in both directions:
 
- - The imported function ABI is used with the following properties
+- The imported function ABI is used with the following properties
 
-    - (unchanged) List and string arguments are passed as Views, no free
-      required, lifetime is constrained until the end of the call
+  - (unchanged) List and string arguments are passed as Views, no free
+    required, lifetime is constrained until the end of the call
 
-    - (unchanged) Owned resources in arguments or results pass ownership
-      to the callee
+  - (unchanged) Owned resources in arguments or results pass ownership
+    to the callee
 
-    - (unchanged) If there are too many (>1) flat results, a local
-      uninitialized ret_area is passed via the last argument
+  - (unchanged) If there are too many (>1) flat results, a local
+    uninitialized ret_area is passed via the last argument
 
-    - (unchanged) Returned objects are owned.
-      For functional safety, i.e. avoiding all
-      allocations in the hot path, the hope is with #385.
+  - (unchanged) Returned objects are owned.
+    For functional safety, i.e. avoiding all
+    allocations in the hot path, the hope is with [#385](https://github.com/WebAssembly/component-model/issues/385).
 
- - The imported resource ABI is used also for exporting
-   with one modification:
+- The imported resource ABI is used also for exporting
+  with one modification:
 
-   Resource IDs are usize, so you can optimize the resource table away.
+   Resource IDs become usize, so you can optimize the resource table away.