bigfoot_ref

docs/source/languages/cpp.md

@@ -242,55 +242,41 @@ provide the following functions to aide in the serialization process:
     }
 ```
 
--   `native_type_template("type")` (on a struct) together with
-    `native_type_template_arg("type")` (on a field of that struct type):
-    lets a single struct declaration back a native type that is a C++
-    template, instantiated differently per field, instead of requiring one
-    struct declaration (and `native_type`) per instantiation.
-    `native_type_template_arg` is angle-bracket-appended to
-    `native_type_template` to form the field's native type, so
-    `native_type_template: "Native::Box"` with
-    `native_type_template_arg: "Native::TypeA"` produces
-    `Native::Box<Native::TypeA>`. For example:
+-   `bigfoot_ref_wrapper("type")` (on a struct) together with `bigfoot_ref("type")`
+    (on a field of that struct type): Bigfoot-specific sugar for a
+    UUID-addressed reference to another native type. `bigfoot_ref_wrapper`
+    marks a struct as a reference-wrapper template (e.g. Bigfoot's
+    `HardReference`/`SoftReference`); `bigfoot_ref` on a field of that type
+    names the referenced native type, e.g. `bigfoot_ref: "::Bigfoot::AssetA"`
+    on a `HardReference`-typed field with `bigfoot_ref_wrapper:
+    "::Bigfoot::HardReference"` produces the field's native type
+    `::Bigfoot::HardReference<::Bigfoot::AssetA>` (auto-deriving a
+    `native_type_pack_name` of `HardReferenceAssetA`, same short-name
+    convention as `native_type_pack_name`). Unlike a hand-written
+    `native_type`, `bigfoot_ref` also emits, directly into the generated
+    header:
+    -   a forward declaration of the referenced type (so the referencing
+        schema's generated header never needs that type's real definition -
+        only the wrapper template's constructor and a `GetUUID()` accessor
+        are used, and those don't require the referenced type to be
+        complete), and
+    -   `inline` `Pack<Name>`/`UnPack<Name>` definitions for it (so no
+        hand-written implementation is required anywhere).
 
 ```cpp
-    struct Box (native_type_template: "Native::Box") {
-      value: int32;
+    struct HardReference (bigfoot_ref_wrapper: "::Bigfoot::HardReference") {
+      uuid: UUID;
     }
 
-    table Example {
-      a: Box (native_inline, native_type_template_arg: "Native::TypeA");
-      b: Box (native_inline, native_type_template_arg: "Native::TypeB");
+    table AssetB {
+      ref_a: HardReference (bigfoot_ref: "::Bigfoot::AssetA");
     }
 ```
 
-is equivalent to writing, on each field itself:
-
-```cpp
-      a: Box (native_inline, native_type: "Native::Box<Native::TypeA>", native_type_pack_name: "BoxTypeA");
-      b: Box (native_inline, native_type: "Native::Box<Native::TypeB>", native_type_pack_name: "BoxTypeB");
-```
-
-`native_type_template_arg` also auto-derives a `native_type_pack_name` of
-`<StructName><ArgShortName>` (here, `BoxTypeA`/`BoxTypeB`) so the Pack/UnPack
-functions stay unique across instantiations without spelling it out
-yourself; an explicit `native_type_pack_name` on the field still overrides
-this. More than one template parameter is supported by separating them with
-commas:
-
-```cpp
-    struct Pair (native_type_template: "Native::Pair") {
-      value: int32;
-    }
-
-    table Example2 {
-      p: Pair (native_inline, native_type_template_arg: "Native::Key, Native::Value");
-    }
-```
-
-which produces `Native::Pair<Native::Key, Native::Value>`.
-`native_type_template_arg` is only valid on fields whose type is a struct
-(or vector of structs) that declares `native_type_template`.
+    is enough on its own - no forward declaration of `::Bigfoot::AssetA` and
+    no `flatbuffers::Pack/UnPackHardReferenceAssetA` implementation need to
+    be written by hand. `bigfoot_ref` is only valid on fields whose type is a
+    struct (or vector of structs) that declares `bigfoot_ref_wrapper`.
 
 -   `native_type("type")` (on a table): Tables can also be represented with
 native types. For example, the following schema: