From d10809ebd48ce461da9dc9242145f6c6504daf63 Mon Sep 17 00:00:00 2001
From: David Hedin <dhedin@movensys.com>
Date: Mon, 30 Mar 2026 01:25:28 -0400
Subject: [PATCH 1/2] Add documentation for namespaces and fixup newlines

---
 crates/cpp/src/lib.rs | 30 +++++++++++++++++++++++++-----
 1 file changed, 25 insertions(+), 5 deletions(-)

diff --git a/crates/cpp/src/lib.rs b/crates/cpp/src/lib.rs
index 271c4fe30..d591a5551 100644
--- a/crates/cpp/src/lib.rs
+++ b/crates/cpp/src/lib.rs
@@ -532,9 +532,11 @@ impl WorldGenerator for Cpp {
                 let binding = Some(name);
                 let mut r#gen = self.interface(resolve, binding, true, Some(wasm_import_module));
                 r#gen.interface = Some(id);
-                r#gen.types(id);
                 let namespace =
                     namespace(resolve, &TypeOwner::Interface(id), false, &r#gen.r#gen.opts);
+                let docs = resolve.interfaces[id].docs.contents.as_deref();
+                r#gen.r#gen.h_src.change_namespace_with_docs(&namespace, docs);
+                r#gen.types(id);
 
                 for (_name, func) in resolve.interfaces[id].functions.iter() {
                     if matches!(func.kind, FunctionKind::Freestanding) {
@@ -583,8 +585,10 @@ impl WorldGenerator for Cpp {
         let binding = Some(name);
         let mut r#gen = self.interface(resolve, binding, false, Some(wasm_import_module));
         r#gen.interface = Some(id);
-        r#gen.types(id);
         let namespace = namespace(resolve, &TypeOwner::Interface(id), true, &r#gen.r#gen.opts);
+        let docs = resolve.interfaces[id].docs.contents.as_deref();
+        r#gen.r#gen.h_src.change_namespace_with_docs(&namespace, docs);
+        r#gen.types(id);
 
         for (_name, func) in resolve.interfaces[id].functions.iter() {
             if matches!(func.kind, FunctionKind::Freestanding) {
@@ -791,6 +795,10 @@ fn namespace(resolve: &Resolve, owner: &TypeOwner, guest_export: bool, opts: &Op
 
 impl SourceWithState {
     fn change_namespace(&mut self, target: &[String]) {
+        self.change_namespace_with_docs(target, None);
+    }
+
+    fn change_namespace_with_docs(&mut self, target: &[String], docs: Option<&str>) {
         let mut same = 0;
         // itertools::fold_while?
         for (a, b) in self.namespace.iter().zip(target.iter()) {
@@ -804,9 +812,17 @@ impl SourceWithState {
             uwrite!(self.src, "}}\n");
         }
         self.namespace.truncate(same);
-        for i in target.iter().skip(same) {
-            uwrite!(self.src, "namespace {} {{\n", i);
-            self.namespace.push(i.clone());
+        let new_namespaces: Vec<_> = target.iter().skip(same).collect();
+        if !new_namespaces.is_empty() {
+            if let Some(content) = docs {
+                for line in content.trim().lines() {
+                    uwriteln!(self.src, "/// {}", line);
+                }
+            }
+            for i in &new_namespaces {
+                uwrite!(self.src, "namespace {} {{\n", i);
+                self.namespace.push(i.to_string());
+            }
         }
     }
 
@@ -1289,6 +1305,10 @@ impl CppInterfaceGenerator<'_> {
             AbiVariant::GuestExportAsync => todo!(),
             AbiVariant::GuestExportAsyncStackful => todo!(),
         };
+        if func.docs.contents.is_some() && !self.r#gen.h_src.src.ends_with('\n') {
+            uwriteln!(self.r#gen.h_src.src, "");
+        }
+        Self::docs(&mut self.r#gen.h_src.src, &func.docs);
         let params = self.print_signature(func, variant, !export);
         let special = is_special_method(func);
         if !matches!(special, SpecialMethod::Allocate) {

From 522f2ec059b4583fc181fe465fce14d1a5117cc3 Mon Sep 17 00:00:00 2001
From: David Hedin <dhedin@movensys.com>
Date: Mon, 30 Mar 2026 03:47:28 -0400
Subject: [PATCH 2/2] Format

---
 crates/cpp/src/lib.rs | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/crates/cpp/src/lib.rs b/crates/cpp/src/lib.rs
index d591a5551..738b45b75 100644
--- a/crates/cpp/src/lib.rs
+++ b/crates/cpp/src/lib.rs
@@ -535,7 +535,10 @@ impl WorldGenerator for Cpp {
                 let namespace =
                     namespace(resolve, &TypeOwner::Interface(id), false, &r#gen.r#gen.opts);
                 let docs = resolve.interfaces[id].docs.contents.as_deref();
-                r#gen.r#gen.h_src.change_namespace_with_docs(&namespace, docs);
+                r#gen
+                    .r#gen
+                    .h_src
+                    .change_namespace_with_docs(&namespace, docs);
                 r#gen.types(id);
 
                 for (_name, func) in resolve.interfaces[id].functions.iter() {
@@ -587,7 +590,10 @@ impl WorldGenerator for Cpp {
         r#gen.interface = Some(id);
         let namespace = namespace(resolve, &TypeOwner::Interface(id), true, &r#gen.r#gen.opts);
         let docs = resolve.interfaces[id].docs.contents.as_deref();
-        r#gen.r#gen.h_src.change_namespace_with_docs(&namespace, docs);
+        r#gen
+            .r#gen
+            .h_src
+            .change_namespace_with_docs(&namespace, docs);
         r#gen.types(id);
 
         for (_name, func) in resolve.interfaces[id].functions.iter() {