Generate C++ code docs (#85)

* drive-by: Add some miscellaneous code docs * Add support for generating C++ comments * Add new snapshots for documentation of C++ structs * Generate documentation for the Deleter structs * Update snapshots for the Deleter comment * Fix misplaced comments in c++ docs * Re-generated the c++ examples
rust-diplomat · Sep 16, 2021 · fb943bf · fb943bf
1 parent d98d31b
commit fb943bf
Show file tree

Hide file tree

Showing 33 changed files with 315 additions and 3 deletions.
diff --git a/example/cpp/ICU4XDataProvider.hpp b/example/cpp/ICU4XDataProvider.hpp
@@ -15,13 +15,20 @@ namespace capi {
 
 class ICU4XDataProvider;
 
+/**
+ * A destruction policy for using ICU4XDataProvider with std::unique_ptr.
+ */
 struct ICU4XDataProviderDeleter {
   void operator()(capi::ICU4XDataProvider* l) const noexcept {
     capi::ICU4XDataProvider_destroy(l);
   }
 };
 class ICU4XDataProvider {
  public:
+
+  /**
+   * Construct a [StaticDataProvider](https://unicode-org.github.io/icu4x-docs/doc/icu_testdata/fn.get_static_provider.html).
+   */
   static ICU4XDataProvider new_static();
   inline const capi::ICU4XDataProvider* AsFFI() const { return this->inner.get(); }
   inline capi::ICU4XDataProvider* AsFFIMut() { return this->inner.get(); }

diff --git a/example/cpp/ICU4XFixedDecimal.hpp b/example/cpp/ICU4XFixedDecimal.hpp
@@ -15,17 +15,44 @@ namespace capi {
 
 class ICU4XFixedDecimal;
 
+/**
+ * A destruction policy for using ICU4XFixedDecimal with std::unique_ptr.
+ */
 struct ICU4XFixedDecimalDeleter {
   void operator()(capi::ICU4XFixedDecimal* l) const noexcept {
     capi::ICU4XFixedDecimal_destroy(l);
   }
 };
 class ICU4XFixedDecimal {
  public:
+
+  /**
+   * Construct an [`ICU4XFixedDecimal`] from an integer.
+   */
   static ICU4XFixedDecimal new_(int32_t v);
+
+  /**
+   * Multiply the [`ICU4XFixedDecimal`] by a given power of ten.
+   * See [the Rust docs](https://unicode-org.github.io/icu4x-docs/doc/fixed_decimal/decimal/struct.FixedDecimal.html#method.multiply_pow10) for more information.
+   */
   void multiply_pow10(int16_t power);
+
+  /**
+   * Invert the sign of the [`ICU4XFixedDecimal`].
+   * See [the Rust docs](https://unicode-org.github.io/icu4x-docs/doc/fixed_decimal/decimal/struct.FixedDecimal.html#method.negate) for more information.
+   */
   void negate();
+
+  /**
+   * Format the [`ICU4XFixedDecimal`] as a string.
+   * See [the Rust docs](https://unicode-org.github.io/icu4x-docs/doc/fixed_decimal/decimal/struct.FixedDecimal.html#method.write_to) for more information.
+   */
   template<typename W> diplomat::result<std::monostate, std::monostate> to_string_to_writeable(W& to) const;
+
+  /**
+   * Format the [`ICU4XFixedDecimal`] as a string.
+   * See [the Rust docs](https://unicode-org.github.io/icu4x-docs/doc/fixed_decimal/decimal/struct.FixedDecimal.html#method.write_to) for more information.
+   */
   diplomat::result<std::string, std::monostate> to_string() const;
   inline const capi::ICU4XFixedDecimal* AsFFI() const { return this->inner.get(); }
   inline capi::ICU4XFixedDecimal* AsFFIMut() { return this->inner.get(); }

diff --git a/example/cpp/ICU4XFixedDecimalFormat.hpp b/example/cpp/ICU4XFixedDecimalFormat.hpp
@@ -19,15 +19,30 @@ struct ICU4XFixedDecimalFormatOptions;
 struct ICU4XFixedDecimalFormatResult;
 class ICU4XFixedDecimal;
 
+/**
+ * A destruction policy for using ICU4XFixedDecimalFormat with std::unique_ptr.
+ */
 struct ICU4XFixedDecimalFormatDeleter {
   void operator()(capi::ICU4XFixedDecimalFormat* l) const noexcept {
     capi::ICU4XFixedDecimalFormat_destroy(l);
   }
 };
 class ICU4XFixedDecimalFormat {
  public:
+
+  /**
+   * Creates a new [`ICU4XFixedDecimalFormat`] from locale data. See [the Rust docs](https://unicode-org.github.io/icu4x-docs/doc/icu/decimal/struct.FixedDecimalFormat.html#method.try_new) for more information.
+   */
   static ICU4XFixedDecimalFormatResult try_new(const ICU4XLocale& locale, const ICU4XDataProvider& provider, ICU4XFixedDecimalFormatOptions options);
+
+  /**
+   * Formats a [`ICU4XFixedDecimal`] to a string. See [the Rust docs](https://unicode-org.github.io/icu4x-docs/doc/icu/decimal/struct.FixedDecimalFormat.html#method.format) for more information.
+   */
   template<typename W> void format_write_to_writeable(const ICU4XFixedDecimal& value, W& write) const;
+
+  /**
+   * Formats a [`ICU4XFixedDecimal`] to a string. See [the Rust docs](https://unicode-org.github.io/icu4x-docs/doc/icu/decimal/struct.FixedDecimalFormat.html#method.format) for more information.
+   */
   std::string format_write(const ICU4XFixedDecimal& value) const;
   inline const capi::ICU4XFixedDecimalFormat* AsFFI() const { return this->inner.get(); }
   inline capi::ICU4XFixedDecimalFormat* AsFFIMut() { return this->inner.get(); }

diff --git a/example/cpp/ICU4XFixedDecimalFormatOptions.hpp b/example/cpp/ICU4XFixedDecimalFormatOptions.hpp
@@ -17,6 +17,9 @@ namespace capi {
 #include "ICU4XFixedDecimalSignDisplay.hpp"
 struct ICU4XFixedDecimalFormatOptions;
 
+/**
+ * A destruction policy for using ICU4XFixedDecimalFormatOptions with std::unique_ptr.
+ */
 struct ICU4XFixedDecimalFormatOptionsDeleter {
   void operator()(capi::ICU4XFixedDecimalFormatOptions* l) const noexcept {
     capi::ICU4XFixedDecimalFormatOptions_destroy(l);

diff --git a/example/cpp/ICU4XFixedDecimalFormatResult.hpp b/example/cpp/ICU4XFixedDecimalFormatResult.hpp
@@ -15,14 +15,25 @@ namespace capi {
 
 class ICU4XFixedDecimalFormat;
 
+/**
+ * A destruction policy for using ICU4XFixedDecimalFormatResult with std::unique_ptr.
+ */
 struct ICU4XFixedDecimalFormatResultDeleter {
   void operator()(capi::ICU4XFixedDecimalFormatResult* l) const noexcept {
     capi::ICU4XFixedDecimalFormatResult_destroy(l);
   }
 };
 struct ICU4XFixedDecimalFormatResult {
  public:
+
+  /**
+   * The [`ICU4XFixedDecimalFormat`], exists if creation was successful.
+   */
   std::optional<ICU4XFixedDecimalFormat> fdf;
+
+  /**
+   * Whether creating the [`ICU4XFixedDecimalFormat`] was successful.
+   */
   bool success;
 };
 

diff --git a/example/cpp/ICU4XLocale.hpp b/example/cpp/ICU4XLocale.hpp
@@ -15,13 +15,20 @@ namespace capi {
 
 class ICU4XLocale;
 
+/**
+ * A destruction policy for using ICU4XLocale with std::unique_ptr.
+ */
 struct ICU4XLocaleDeleter {
   void operator()(capi::ICU4XLocale* l) const noexcept {
     capi::ICU4XLocale_destroy(l);
   }
 };
 class ICU4XLocale {
  public:
+
+  /**
+   * Construct an [`ICU4XLocale`] from an locale identifier.
+   */
   static ICU4XLocale new_(const std::string_view name);
   inline const capi::ICU4XLocale* AsFFI() const { return this->inner.get(); }
   inline capi::ICU4XLocale* AsFFIMut() { return this->inner.get(); }

diff --git a/tool/src/cpp/conversions.rs b/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,
 }
 

diff --git a/tool/src/cpp/mod.rs b/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
+                }
+            }
+        }
+    }
 }
diff --git a/tool/src/cpp/snapshots/diplomat_tool__cpp__conversions__tests__enum_conversion@Foo.hpp.snap b/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);

diff --git a/...c/cpp/snapshots/diplomat_tool__cpp__conversions__tests__enum_conversion@MyStruct.hpp.snap b/...c/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);

diff --git a/...src/cpp/snapshots/diplomat_tool__cpp__structs__tests__method_taking_str@MyStruct.hpp.snap b/...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);

diff --git a/.../cpp/snapshots/diplomat_tool__cpp__structs__tests__method_writeable_out@MyStruct.hpp.snap b/.../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);

diff --git a/.../snapshots/diplomat_tool__cpp__structs__tests__simple_non_opaque_struct@MyStruct.hpp.snap b/.../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);

diff --git a/.../cpp/snapshots/diplomat_tool__cpp__structs__tests__simple_opaque_struct@MyStruct.hpp.snap b/.../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);

diff --git a/tool/src/cpp/snapshots/diplomat_tool__cpp__structs__tests__struct_documentation@Foo.hpp.snap b/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
diff --git a/tool/src/cpp/snapshots/diplomat_tool__cpp__tests__cross_module_struct_fields@Bar.hpp.snap b/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);

diff --git a/tool/src/cpp/snapshots/diplomat_tool__cpp__tests__cross_module_struct_fields@Foo.hpp.snap b/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);

diff --git a/tool/src/cpp/snapshots/diplomat_tool__cpp__tests__cross_module_struct_methods@Bar.hpp.snap b/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);

diff --git a/tool/src/cpp/snapshots/diplomat_tool__cpp__tests__cross_module_struct_methods@Foo.hpp.snap b/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);