Support for generation of documentation comments for bindings

Cargo.toml

@@ -6,6 +6,7 @@ members = [
   "uniffi_macros",
   "uniffi_meta",
   "uniffi_testing",
+  "uniffi_docs",
   "uniffi",
   "weedle2",
 
@@ -17,6 +18,7 @@ members = [
   "examples/todolist",
   "examples/custom-types",
   "examples/app/uniffi-bindgen-cli",
+  "examples/documentation",
 
   "fixtures/coverall",
   "fixtures/callbacks",

examples/README.md

@@ -18,6 +18,8 @@ Newcomers are recommended to explore them in the following order:
   code, through rust and back again.
 * [`./fxa-client`](./fxa-client/) doesn't work yet, but it contains aspirational example of what the UDL
   might look like for an actual real-world component.
+* [`./documentation`](./documentation/) demonstrates extraction of documentation comments from Rust code
+  and their attachment to the resulting foreign language bindings.
 
 Each example has the following structure:
 
@@ -31,6 +33,7 @@ Each example has the following structure:
   * Kotlin `tests/bindings/test_<namespace>.kts`
   * Swift `tests/bindings/test_<namespace>.swift`
   * Python `tests/bindings/test_<namespace>.py`
+  * Ruby `tests/bindings/test_<namespace>.rb`
 
 If you want to try them out, you will need:
 

examples/documentation/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "uniffi-example-documentation"
+edition = "2021"
+version = "0.23.0"
+license = "MPL-2.0"
+publish = false
+
+[lib]
+crate-type = ["lib", "cdylib"]
+name = "uniffi_documentation"
+
+[dependencies]
+uniffi = { path = "../../uniffi"}
+
+[build-dependencies]
+uniffi = { path = "../../uniffi", features = ["build"] }
+
+[dev-dependencies]
+uniffi = { path = "../../uniffi", features = ["bindgen-tests"] }

examples/documentation/build.rs

@@ -0,0 +1,7 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+fn main() {
+    uniffi::generate_scaffolding("./src/documentation.udl").unwrap();
+}

examples/documentation/src/documentation.udl

@@ -0,0 +1,20 @@
+namespace documentation {
+  string hello(Pet pet);
+  u64 add(u64 a, u64 b);
+};
+
+dictionary Pet {
+  string name;
+};
+
+interface Person {
+  constructor(string name);
+  void set_name(string name);
+  string get_name();
+};
+
+enum TestEnum {
+  "A",
+  "B",
+  "C",
+};

examples/documentation/src/lib.rs

@@ -0,0 +1,56 @@
+use std::sync::RwLock;
+
+/// Pet with a name.
+pub struct Pet {
+    /// Pet's name.
+    pub name: String,
+}
+
+/// Create hello message to a `pet`.
+pub fn hello(pet: Pet) -> String {
+    let name = pet.name;
+    format!("Hello {name}!")
+}
+
+/// Person with a name.
+pub struct Person {
+    name: RwLock<String>,
+}
+
+impl Person {
+    /// Create new person with [name].
+    pub fn new(name: String) -> Self {
+        Person {
+            name: RwLock::new(name),
+        }
+    }
+
+    /// Set person name.
+    pub fn set_name(&self, name: String) {
+        *self.name.write().unwrap() = name;
+    }
+
+    /// Get person's name.
+    pub fn get_name(&self) -> String {
+        self.name.read().unwrap().clone()
+    }
+}
+
+/// Add two integers together.
+pub fn add(left: u64, right: u64) -> u64 {
+    left + right
+}
+
+/// Test enum.
+pub enum TestEnum {
+    /// Variant A.
+    A,
+
+    /// Variant B.
+    B,
+
+    /// Variant C.
+    C,
+}
+
+uniffi::include_scaffolding!("documentation");

examples/documentation/tests/bindings/test_documentation.kts

@@ -0,0 +1,5 @@
+import uniffi.documentation.*
+
+assert(hello(Pet("Tom")) == "Hello Tom!")
+assert(Person("Daniel").getName() == "Daniel")
+assert(add(2UL, 4UL) == 6UL)

examples/documentation/tests/bindings/test_documentation.py

@@ -0,0 +1,19 @@
+import unittest
+import documentation
+
+class TestHello(unittest.TestCase):
+    def test_hello(self):
+        self.assertEqual(documentation.hello(documentation.Pet("Tom")),
+                         "Hello Tom!", "Should be `Hello Tom!`")
+
+class TestGetName(unittest.TestCase):
+    def test_get_name(self):
+        self.assertEqual(documentation.Person("Daniel").get_name(), "Daniel", "Should be Daniel")
+
+class TestAdd(unittest.TestCase):
+    def test_add(self):
+        self.assertEqual(documentation.add(2, 4), 6, "Should be 6")
+
+
+if __name__ == '__main__':
+    unittest.main()

examples/documentation/tests/bindings/test_documentation.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'test/unit'
+require 'documentation'
+
+include Test::Unit::Assertions
+
+assert_equal Documentation.hello(Documentation::Pet.new("Tom")), "Hello Tom!"
+assert_equal Documentation::Person.new("Daniel").get_name(), "Daniel"
+assert_equal Documentation.add(2, 4), 6

examples/documentation/tests/bindings/test_documentation.swift

@@ -0,0 +1,5 @@
+import documentation
+
+assert(hello(pet: Pet(name: "Tom")) == "Hello Tom!", "hello works")
+assert(Person(name: "Daniel").getName() == "Daniel", "getName works")
+assert(add(a: 2, b: 4) == 6, "add works")

examples/documentation/tests/test_generated_bindings.rs

@@ -0,0 +1,6 @@
+uniffi::build_foreign_language_testcases!(
+    "tests/bindings/test_documentation.py",
+    "tests/bindings/test_documentation.rb",
+    "tests/bindings/test_documentation.kts",
+    "tests/bindings/test_documentation.swift",
+);

examples/documentation/uniffi.toml

@@ -0,0 +1,2 @@
+[bindings]
+doc_comments = true

uniffi_bindgen/Cargo.toml

@@ -27,3 +27,4 @@ toml = "0.5"
 weedle2 = { version = "4.0.0", path = "../weedle2" }
 uniffi_meta = { path = "../uniffi_meta", version = "=0.23.0" }
 uniffi_testing = { path = "../uniffi_testing", version = "=0.23.0" }
+uniffi_docs = { path = "../uniffi_docs", version = "=0.23.0" }

uniffi_bindgen/src/bindings/kotlin/templates/EnumTemplate.kt

@@ -8,8 +8,10 @@
 
 {%- if e.is_flat() %}
 
+{% let struct = e %}{% include "StructureDocsTemplate.kt" %}
 enum class {{ type_name }} {
     {% for variant in e.variants() -%}
+    {% include "EnumVariantDocsTemplate.kt" %}
     {{ variant.name()|enum_variant }}{% if loop.last %};{% else %},{% endif %}
     {%- endfor %}
 }
@@ -30,6 +32,7 @@ public object {{ e|ffi_converter_name }}: FfiConverterRustBuffer<{{ type_name }}
 
 {% else %}
 
+{% let struct = e %}{% include "StructureDocsTemplate.kt" %}
 sealed class {{ type_name }}{% if contains_object_references %}: Disposable {% endif %} {
     {% for variant in e.variants() -%}
     {% if !variant.has_fields() -%}

uniffi_bindgen/src/bindings/kotlin/templates/EnumVariantDocsTemplate.kt

@@ -0,0 +1,7 @@
+{% match variant.documentation() -%}
+  {% when Some with (docs) %}
+    /**
+{% for line in docs.lines() %}     * {{ line }} 
+{% endfor %}     */
+  {%- when None %}
+{%- endmatch %}

uniffi_bindgen/src/bindings/kotlin/templates/FunctionDocsTemplate.kt

@@ -0,0 +1,20 @@
+
+{% match func.documentation() -%}
+  {% when Some with (docs) %}
+    /**
+    {% for line in docs.description.lines() %} * {{ line }} 
+    {% endfor %}
+
+    {%- if docs.arguments_descriptions.len() > 0 %} *
+    {% for arg in func.arguments() -%}
+      * @param [{{ arg.name() }}] {{ docs.arguments_descriptions[arg.name()] }}
+    {% endfor -%} 
+    {% endif -%}
+
+    {%- match docs.return_description -%}
+      {% when Some with (desc) %} *
+     * @return {{ desc }}
+      {%- when None %}
+    {%- endmatch %} */
+  {%- when None %}
+{%- endmatch %}

uniffi_bindgen/src/bindings/kotlin/templates/ObjectTemplate.kt

@@ -5,6 +5,8 @@
 
 public interface {{ type_name }}Interface {
     {% for meth in obj.methods() -%}
+    {%- let func = meth -%}
+    {%- include "FunctionDocsTemplate.kt" -%}
     {%- match meth.throws_type() -%}
     {%- when Some with (throwable) -%}
     @Throws({{ throwable|type_name }}::class)
@@ -23,12 +25,15 @@ public interface {{ type_name }}Interface {
     {% endfor %}
 }
 
+{% let struct = obj %}{% include "StructureDocsTemplate.kt" %}
 class {{ type_name }}(
     pointer: Pointer
 ) : FFIObject(pointer), {{ type_name }}Interface {
 
     {%- match obj.primary_constructor() %}
     {%- when Some with (cons) %}
+    {%- let func = cons -%}
+    {%- include "FunctionDocsTemplate.kt" %}
     constructor({% call kt::arg_list_decl(cons) -%}) :
         this({% call kt::to_ffi_call(cons) %})
     {%- when None %}
@@ -78,6 +83,8 @@ class {{ type_name }}(
     {% if !obj.alternate_constructors().is_empty() -%}
     companion object {
         {% for cons in obj.alternate_constructors() -%}
+        {%- let func = cons -%}
+        {%- include "FunctionDocsTemplate.kt" %}
         fun {{ cons.name()|fn_name }}({% call kt::arg_list_decl(cons) %}): {{ type_name }} =
             {{ type_name }}({% call kt::to_ffi_call(cons) %})
         {% endfor %}

uniffi_bindgen/src/bindings/kotlin/templates/RecordDocsTemplate.kt

@@ -0,0 +1,15 @@
+{% match struct.documentation() -%}
+  {% when Some with (docs) %}
+/**
+{% for line in docs.description.lines() %} * {{ line }} 
+{% endfor %}
+{%- if struct.has_fields_documentation() %} *
+{% endif -%}
+{% for f in struct.fields() -%}
+{% match f.documentation() -%}
+{% when Some with (docs) %} * @property {{ f.name() }} {{ docs }}
+{% when None %}
+{%- endmatch %}
+{%- endfor %} */
+  {%- when None %}
+{%- endmatch %}

uniffi_bindgen/src/bindings/kotlin/templates/RecordTemplate.kt

@@ -1,5 +1,6 @@
 {%- let rec = ci.get_record_definition(name).unwrap() %}
 
+{% let struct = rec %}{% include "RecordDocsTemplate.kt" %}
 data class {{ type_name }} (
     {%- for field in rec.fields() %}
     var {{ field.name()|var_name }}: {{ field|type_name -}}

uniffi_bindgen/src/bindings/kotlin/templates/StructureDocsTemplate.kt

@@ -0,0 +1,7 @@
+{% match struct.documentation() -%}
+  {% when Some with (docs) %}
+/**
+{% for line in docs.description.lines() %} * {{ line }} 
+{% endfor %} */
+  {%- when None %}
+{%- endmatch %}

uniffi_bindgen/src/bindings/kotlin/templates/TopLevelFunctionTemplate.kt

@@ -7,6 +7,7 @@
 
     {%- call kt::async_func(func) -%}
 {%- else %}
+{% include "FunctionDocsTemplate.kt" %}
     {%- match func.throws_type() -%}
     {%- when Some with (throwable) %}
         @Throws({{ throwable|type_name }}::class)

uniffi_bindgen/src/bindings/kotlin/templates/wrapper.kt

@@ -55,7 +55,7 @@ import kotlinx.coroutines.sync.withPermit
 {{ type_helper_code }}
 
 {%- for func in ci.function_definitions() %}
-{%- include "TopLevelFunctionTemplate.kt" %}
+{% include "TopLevelFunctionTemplate.kt" %}
 {%- endfor %}
 
 {% import "macros.kt" as kt %}

uniffi_bindgen/src/bindings/mod.rs

@@ -65,6 +65,8 @@ impl TryFrom<String> for TargetLanguage {
 
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 pub struct Config {
+    #[serde(default)]
+    pub doc_comments: Option<bool>,
     #[serde(default)]
     kotlin: kotlin::Config,
     #[serde(default)]
@@ -78,6 +80,7 @@ pub struct Config {
 impl From<&ComponentInterface> for Config {
     fn from(ci: &ComponentInterface) -> Self {
         Config {
+            doc_comments: None,
             kotlin: ci.into(),
             swift: ci.into(),
             python: ci.into(),
@@ -89,6 +92,7 @@ impl From<&ComponentInterface> for Config {
 impl MergeWith for Config {
     fn merge_with(&self, other: &Self) -> Self {
         Config {
+            doc_comments: self.doc_comments.merge_with(&other.doc_comments),
             kotlin: self.kotlin.merge_with(&other.kotlin),
             swift: self.swift.merge_with(&other.swift),
             python: self.python.merge_with(&other.python),

uniffi_bindgen/src/bindings/python/templates/EnumTemplate.py

@@ -7,13 +7,14 @@
 {%- let e = ci.get_enum_definition(name).unwrap() %}
 {% if e.is_flat() %}
 
-class {{ type_name }}(enum.Enum):
+class {{ type_name }}(enum.Enum): {% let struct = e %}{% include "StructureDocsTemplate.py" %}
     {% for variant in e.variants() -%}
     {{ variant.name()|enum_variant_py }} = {{ loop.index }}
+    {% include "EnumVariantDocsTemplate.py" %}
     {% endfor %}
 {% else %}
 
-class {{ type_name }}:
+class {{ type_name }}: {% let struct = e %}{% include "StructureDocsTemplate.py" %}
     def __init__(self):
         raise RuntimeError("{{ type_name }} cannot be instantiated directly")
 

uniffi_bindgen/src/bindings/python/templates/EnumVariantDocsTemplate.py

@@ -0,0 +1,6 @@
+{% match variant.documentation() -%}
+{% when Some with (docs) %}"""
+{% for line in docs.lines() %}    {{ line }} 
+{% endfor %}    """
+{%- when None %}
+{%- endmatch %}