Generate C++ code docs

tool/src/cpp/conversions.rs

@@ -147,9 +147,12 @@ pub fn gen_rust_to_cpp<W: Write>(
     }
 }
 
+/// Meta information about a [ast::TypeName::Reference].
 #[derive(Eq, PartialEq)]
 pub struct ReferenceMeta {
+    /// Whether or not the reference is owned.
     owned: bool,
+    /// Whether or not the reference is mutable.
     mutable: bool,
 }
 

tool/src/cpp/mod.rs

@@ -14,6 +14,8 @@ mod types;
 mod structs;
 use structs::*;
 
+use crate::cpp::util::gen_comment_block;
+
 mod conversions;
 
 pub mod docs;
@@ -66,9 +68,11 @@ pub fn gen_bindings(
 
             ast::CustomType::Enum(enm) => {
                 writeln!(out)?;
+                gen_comment_block(out, &enm.doc_lines)?;
                 writeln!(out, "enum struct {} {{", enm.name)?;
                 let mut enm_indent = indented(out).with_str("  ");
-                for (name, discriminant, _) in enm.variants.iter() {
+                for (name, discriminant, doc_lines) in enm.variants.iter() {
+                    gen_comment_block(&mut enm_indent, doc_lines)?;
                     writeln!(&mut enm_indent, "{} = {},", name, discriminant)?;
                 }
                 writeln!(out, "}};")?;
@@ -358,4 +362,22 @@ mod tests {
             }
         }
     }
+
+    #[test]
+    fn test_enum_documentation() {
+        test_file! {
+            #[diplomat::bridge]
+            mod ffi {
+                /// Documentation for MyEnum.
+                enum MyEnum {
+                    /// All about A.
+                    A,
+                    /// All about B.
+                    B,
+                    /// All about C.
+                    C
+                }
+            }
+        }
+    }
 }

tool/src/cpp/snapshots/diplomat_tool__cpp__conversions__tests__enum_conversion@Foo.hpp.snap

@@ -20,6 +20,9 @@ namespace capi {
 
 struct MyStruct;
 
+/**
+ * A destruction policy for using Foo with std::unique_ptr.
+ */
 struct FooDeleter {
   void operator()(capi::Foo* l) const noexcept {
     capi::Foo_destroy(l);

tool/src/cpp/snapshots/diplomat_tool__cpp__conversions__tests__enum_conversion@MyStruct.hpp.snap

@@ -20,6 +20,9 @@ namespace capi {
 
 #include "MyEnum.hpp"
 
+/**
+ * A destruction policy for using MyStruct with std::unique_ptr.
+ */
 struct MyStructDeleter {
   void operator()(capi::MyStruct* l) const noexcept {
     capi::MyStruct_destroy(l);

tool/src/cpp/snapshots/diplomat_tool__cpp__structs__tests__method_taking_str@MyStruct.hpp.snap

@@ -20,6 +20,9 @@ namespace capi {
 
 class MyStruct;
 
+/**
+ * A destruction policy for using MyStruct with std::unique_ptr.
+ */
 struct MyStructDeleter {
   void operator()(capi::MyStruct* l) const noexcept {
     capi::MyStruct_destroy(l);

tool/src/cpp/snapshots/diplomat_tool__cpp__structs__tests__method_writeable_out@MyStruct.hpp.snap

@@ -19,6 +19,9 @@ namespace capi {
 }
 
 
+/**
+ * A destruction policy for using MyStruct with std::unique_ptr.
+ */
 struct MyStructDeleter {
   void operator()(capi::MyStruct* l) const noexcept {
     capi::MyStruct_destroy(l);

tool/src/cpp/snapshots/diplomat_tool__cpp__structs__tests__simple_non_opaque_struct@MyStruct.hpp.snap

@@ -20,6 +20,9 @@ namespace capi {
 
 struct MyStruct;
 
+/**
+ * A destruction policy for using MyStruct with std::unique_ptr.
+ */
 struct MyStructDeleter {
   void operator()(capi::MyStruct* l) const noexcept {
     capi::MyStruct_destroy(l);

tool/src/cpp/snapshots/diplomat_tool__cpp__structs__tests__simple_opaque_struct@MyStruct.hpp.snap

@@ -20,6 +20,9 @@ namespace capi {
 
 class MyStruct;
 
+/**
+ * A destruction policy for using MyStruct with std::unique_ptr.
+ */
 struct MyStructDeleter {
   void operator()(capi::MyStruct* l) const noexcept {
     capi::MyStruct_destroy(l);

tool/src/cpp/snapshots/diplomat_tool__cpp__structs__tests__struct_documentation@Foo.hpp.snap

@@ -0,0 +1,53 @@
+---
+source: tool/src/cpp/structs.rs
+expression: out_texts.get(out).unwrap()
+
+---
+#ifndef Foo_HPP
+#define Foo_HPP
+#include <stdint.h>
+#include <stddef.h>
+#include <stdbool.h>
+#include <algorithm>
+#include <memory>
+#include <optional>
+#include <variant>
+#include "diplomat_runtime.hpp"
+
+namespace capi {
+#include "Foo.h"
+}
+
+
+/**
+ * A destruction policy for using Foo with std::unique_ptr.
+ */
+struct FooDeleter {
+  void operator()(capi::Foo* l) const noexcept {
+    capi::Foo_destroy(l);
+  }
+};
+
+/**
+ * Documentation for Foo.
+ * Second line.
+ */
+struct Foo {
+ public:
+
+  /**
+   * Documentation for x.
+   */
+  uint8_t x;
+
+  /**
+   * Documentation for get_x.
+   */
+  uint8_t get_x() const;
+};
+
+
+inline uint8_t Foo::get_x() const {
+  return capi::Foo_get_x((capi::Foo*) &this);
+}
+#endif

tool/src/cpp/snapshots/diplomat_tool__cpp__tests__cross_module_struct_fields@Bar.hpp.snap

@@ -20,6 +20,9 @@ namespace capi {
 
 struct Foo;
 
+/**
+ * A destruction policy for using Bar with std::unique_ptr.
+ */
 struct BarDeleter {
   void operator()(capi::Bar* l) const noexcept {
     capi::Bar_destroy(l);

tool/src/cpp/snapshots/diplomat_tool__cpp__tests__cross_module_struct_fields@Foo.hpp.snap

@@ -20,6 +20,9 @@ namespace capi {
 
 #include "Bar.hpp"
 
+/**
+ * A destruction policy for using Foo with std::unique_ptr.
+ */
 struct FooDeleter {
   void operator()(capi::Foo* l) const noexcept {
     capi::Foo_destroy(l);

tool/src/cpp/snapshots/diplomat_tool__cpp__tests__cross_module_struct_methods@Bar.hpp.snap

@@ -20,6 +20,9 @@ namespace capi {
 
 class Foo;
 
+/**
+ * A destruction policy for using Bar with std::unique_ptr.
+ */
 struct BarDeleter {
   void operator()(capi::Bar* l) const noexcept {
     capi::Bar_destroy(l);

tool/src/cpp/snapshots/diplomat_tool__cpp__tests__cross_module_struct_methods@Foo.hpp.snap

@@ -20,6 +20,9 @@ namespace capi {
 
 struct Bar;
 
+/**
+ * A destruction policy for using Foo with std::unique_ptr.
+ */
 struct FooDeleter {
   void operator()(capi::Foo* l) const noexcept {
     capi::Foo_destroy(l);

tool/src/cpp/snapshots/diplomat_tool__cpp__tests__enum_documentation@MyEnum.hpp.snap

@@ -0,0 +1,45 @@
+---
+source: tool/src/cpp/mod.rs
+expression: out_texts.get(out).unwrap()
+
+---
+#ifndef MyEnum_HPP
+#define MyEnum_HPP
+#include <stdint.h>
+#include <stddef.h>
+#include <stdbool.h>
+#include <algorithm>
+#include <memory>
+#include <optional>
+#include <variant>
+#include "diplomat_runtime.hpp"
+
+namespace capi {
+#include "MyEnum.h"
+}
+
+
+
+/**
+ * Documentation for MyEnum.
+ */
+enum struct MyEnum {
+
+  /**
+   * All about A.
+   */
+  A = 0,
+
+  /**
+   * All about B.
+   */
+  B = 1,
+
+  /**
+   * All about C.
+   */
+  C = 2,
+};
+
+#endif
+

tool/src/cpp/snapshots/diplomat_tool__cpp__types__tests__option_types@MyOpaqueStruct.hpp.snap

@@ -19,6 +19,9 @@ namespace capi {
 }
 
 
+/**
+ * A destruction policy for using MyOpaqueStruct with std::unique_ptr.
+ */
 struct MyOpaqueStructDeleter {
   void operator()(capi::MyOpaqueStruct* l) const noexcept {
     capi::MyOpaqueStruct_destroy(l);

tool/src/cpp/snapshots/diplomat_tool__cpp__types__tests__option_types@MyStruct.hpp.snap

@@ -20,6 +20,9 @@ namespace capi {
 
 class MyOpaqueStruct;
 
+/**
+ * A destruction policy for using MyStruct with std::unique_ptr.
+ */
 struct MyStructDeleter {
   void operator()(capi::MyStruct* l) const noexcept {
     capi::MyStruct_destroy(l);

tool/src/cpp/snapshots/diplomat_tool__cpp__types__tests__pointer_types@MyOpaqueStruct.hpp.snap

@@ -19,6 +19,9 @@ namespace capi {
 }
 
 
+/**
+ * A destruction policy for using MyOpaqueStruct with std::unique_ptr.
+ */
 struct MyOpaqueStructDeleter {
   void operator()(capi::MyOpaqueStruct* l) const noexcept {
     capi::MyOpaqueStruct_destroy(l);

tool/src/cpp/snapshots/diplomat_tool__cpp__types__tests__pointer_types@MyStruct.hpp.snap

@@ -21,6 +21,9 @@ namespace capi {
 class MyOpaqueStruct;
 struct MyStruct;
 
+/**
+ * A destruction policy for using MyStruct with std::unique_ptr.
+ */
 struct MyStructDeleter {
   void operator()(capi::MyStruct* l) const noexcept {
     capi::MyStruct_destroy(l);

tool/src/cpp/snapshots/diplomat_tool__cpp__types__tests__result_types@MyOpaqueStruct.hpp.snap

@@ -19,6 +19,9 @@ namespace capi {
 }
 
 
+/**
+ * A destruction policy for using MyOpaqueStruct with std::unique_ptr.
+ */
 struct MyOpaqueStructDeleter {
   void operator()(capi::MyOpaqueStruct* l) const noexcept {
     capi::MyOpaqueStruct_destroy(l);

tool/src/cpp/snapshots/diplomat_tool__cpp__types__tests__result_types@MyStruct.hpp.snap

@@ -21,6 +21,9 @@ namespace capi {
 class MyOpaqueStruct;
 struct MyStruct;
 
+/**
+ * A destruction policy for using MyStruct with std::unique_ptr.
+ */
 struct MyStructDeleter {
   void operator()(capi::MyStruct* l) const noexcept {
     capi::MyStruct_destroy(l);

tool/src/cpp/snapshots/diplomat_tool__cpp__types__tests__string_reference@MyStruct.hpp.snap

@@ -20,6 +20,9 @@ namespace capi {
 
 struct MyStruct;
 
+/**
+ * A destruction policy for using MyStruct with std::unique_ptr.
+ */
 struct MyStructDeleter {
   void operator()(capi::MyStruct* l) const noexcept {
     capi::MyStruct_destroy(l);

tool/src/cpp/snapshots/diplomat_tool__cpp__types__tests__unit_type@MyStruct.hpp.snap

@@ -19,6 +19,9 @@ namespace capi {
 }
 
 
+/**
+ * A destruction policy for using MyStruct with std::unique_ptr.
+ */
 struct MyStructDeleter {
   void operator()(capi::MyStruct* l) const noexcept {
     capi::MyStruct_destroy(l);

tool/src/cpp/snapshots/diplomat_tool__cpp__types__tests__writeable_out@MyStruct.hpp.snap

@@ -19,6 +19,9 @@ namespace capi {
 }
 
 
+/**
+ * A destruction policy for using MyStruct with std::unique_ptr.
+ */
 struct MyStructDeleter {
   void operator()(capi::MyStruct* l) const noexcept {
     capi::MyStruct_destroy(l);