Generating documentation from the ffi block docs to the kotlin backend

core/src/ast/traits.rs

@@ -26,6 +26,7 @@ pub struct TraitMethod {
     pub output_type: Option<TypeName>,
     pub lifetimes: LifetimeEnv,
     pub attrs: Attrs,
+    pub docs: Docs,
 }
 
 impl Trait {
@@ -100,6 +101,7 @@ impl Trait {
                     output_type,
                     lifetimes,
                     attrs: fct_attrs,
+                    docs: Docs::from_attrs(&fct.attrs),
                 });
             }
         }

core/src/hir/lowering.rs

@@ -461,6 +461,7 @@ impl<'ast> LoweringContext<'ast> {
             output: Box::new(output),
             name: Some(self.lower_ident(&name, "trait name")?),
             attrs: Some(attrs),
+            docs: Some(ast_trait_method.docs.clone()),
         })
     }
 
@@ -930,6 +931,7 @@ impl<'ast> LoweringContext<'ast> {
                     }),
                     name: None,
                     attrs: None,
+                    docs: None,
                 })))
             }
             ast::TypeName::Unit => {

core/src/hir/methods.rs

@@ -55,6 +55,7 @@ pub struct Callback {
     pub output: Box<Option<Type>>, // this will be used in Rust (note: can technically be a callback, or void)
     pub name: Option<IdentBuf>,
     pub attrs: Option<Attrs>,
+    pub docs: Option<Docs>,
 }
 
 // uninstantiatable; represents no callback allowed

example/kotlin/somelib/src/main/kotlin/dev/diplomattest/somelib/DataProvider.kt

@@ -11,7 +11,10 @@ internal interface DataProviderLib: Library {
     fun icu4x_DataProvider_new_static_mv1(): Pointer
     fun icu4x_DataProvider_returns_result_mv1(): ResultUnitUnit
 }
-
+/** An  data provider, capable of loading  data keys from some source.
+*
+*See the [Rust documentation for `icu_provider`](https://docs.rs/icu_provider/latest/icu_provider/index.html) for more information.
+*/
 class DataProvider internal constructor (
     internal val handle: Pointer,
     // These ensure that anything that is borrowed is kept alive and not cleaned
@@ -29,6 +32,8 @@ class DataProvider internal constructor (
         internal val libClass: Class<DataProviderLib> = DataProviderLib::class.java
         internal val lib: DataProviderLib = Native.load("somelib", libClass)
 
+        /** See the [Rust documentation for `get_static_provider`](https://docs.rs/icu_testdata/latest/icu_testdata/fn.get_static_provider.html) for more information.
+        */
         fun newStatic(): DataProvider {
 
             val returnVal = lib.icu4x_DataProvider_new_static_mv1();
@@ -39,6 +44,8 @@ class DataProvider internal constructor (
             return returnOpaque
         }
 
+        /** This exists as a regression test for https://github.com/rust-diplomat/diplomat/issues/155
+        */
         fun returnsResult(): Res<Unit, Unit> {
 
             val returnVal = lib.icu4x_DataProvider_returns_result_mv1();

example/kotlin/somelib/src/main/kotlin/dev/diplomattest/somelib/FixedDecimal.kt

@@ -12,7 +12,8 @@ internal interface FixedDecimalLib: Library {
     fun icu4x_FixedDecimal_multiply_pow10_mv1(handle: Pointer, power: Short): Unit
     fun icu4x_FixedDecimal_to_string_mv1(handle: Pointer, write: Pointer): ResultUnitUnit
 }
-
+/** See the [Rust documentation for `FixedDecimal`](https://docs.rs/fixed_decimal/latest/fixed_decimal/struct.FixedDecimal.html) for more information.
+*/
 class FixedDecimal internal constructor (
     internal val handle: Pointer,
     // These ensure that anything that is borrowed is kept alive and not cleaned
@@ -30,6 +31,8 @@ class FixedDecimal internal constructor (
         internal val libClass: Class<FixedDecimalLib> = FixedDecimalLib::class.java
         internal val lib: FixedDecimalLib = Native.load("somelib", libClass)
 
+        /** Construct an [`FixedDecimal`] from an integer.
+        */
         fun new_(v: Int): FixedDecimal {
 
             val returnVal = lib.icu4x_FixedDecimal_new_mv1(v);
@@ -41,12 +44,20 @@ class FixedDecimal internal constructor (
         }
     }
 
+    /** Multiply the [`FixedDecimal`] by a given power of ten.
+    *
+    *See the [Rust documentation for `multiply_pow10`](https://docs.rs/fixed_decimal/latest/fixed_decimal/struct.FixedDecimal.html#method.multiply_pow10) for more information.
+    */
     fun multiplyPow10(power: Short): Unit {
 
         val returnVal = lib.icu4x_FixedDecimal_multiply_pow10_mv1(handle, power);
 
     }
 
+    /** Format the [`FixedDecimal`] as a string.
+    *
+    *See the [Rust documentation for `write_to`](https://docs.rs/fixed_decimal/latest/fixed_decimal/struct.FixedDecimal.html#method.write_to) for more information.
+    */
     fun toString_(): Res<String, Unit> {
         val write = DW.lib.diplomat_buffer_write_create(0)
         val returnVal = lib.icu4x_FixedDecimal_to_string_mv1(handle, write);

example/kotlin/somelib/src/main/kotlin/dev/diplomattest/somelib/FixedDecimalFormatter.kt

@@ -11,7 +11,10 @@ internal interface FixedDecimalFormatterLib: Library {
     fun icu4x_FixedDecimalFormatter_try_new_mv1(locale: Pointer, provider: Pointer, options: FixedDecimalFormatterOptionsNative): ResultPointerUnit
     fun icu4x_FixedDecimalFormatter_format_write_mv1(handle: Pointer, value: Pointer, write: Pointer): Unit
 }
-
+/** An  Fixed Decimal Format object, capable of formatting a [`FixedDecimal`] as a string.
+*
+*See the [Rust documentation for `FixedDecimalFormatter`](https://docs.rs/icu/latest/icu/decimal/struct.FixedDecimalFormatter.html) for more information.
+*/
 class FixedDecimalFormatter internal constructor (
     internal val handle: Pointer,
     // These ensure that anything that is borrowed is kept alive and not cleaned
@@ -29,6 +32,10 @@ class FixedDecimalFormatter internal constructor (
         internal val libClass: Class<FixedDecimalFormatterLib> = FixedDecimalFormatterLib::class.java
         internal val lib: FixedDecimalFormatterLib = Native.load("somelib", libClass)
 
+        /** Creates a new [`FixedDecimalFormatter`] from locale data.
+        *
+        *See the [Rust documentation for `try_new`](https://docs.rs/icu/latest/icu/decimal/struct.FixedDecimalFormatter.html#method.try_new) for more information.
+        */
         fun tryNew(locale: Locale, provider: DataProvider, options: FixedDecimalFormatterOptions): Res<FixedDecimalFormatter, Unit> {
 
             val returnVal = lib.icu4x_FixedDecimalFormatter_try_new_mv1(locale.handle, provider.handle, options.nativeStruct);
@@ -44,6 +51,10 @@ class FixedDecimalFormatter internal constructor (
         }
     }
 
+    /** Formats a [`FixedDecimal`] to a string.
+    *
+    *See the [Rust documentation for `format`](https://docs.rs/icu/latest/icu/decimal/struct.FixedDecimalFormatter.html#method.format) for more information.
+    */
     fun formatWrite(value: FixedDecimal): String {
         val write = DW.lib.diplomat_buffer_write_create(0)
         val returnVal = lib.icu4x_FixedDecimalFormatter_format_write_mv1(handle, value.handle, write);

example/kotlin/somelib/src/main/kotlin/dev/diplomattest/somelib/Locale.kt

@@ -10,7 +10,10 @@ internal interface LocaleLib: Library {
     fun icu4x_Locale_destroy_mv1(handle: Pointer)
     fun icu4x_Locale_new_mv1(name: Slice): Pointer
 }
-
+/** An  Locale, capable of representing strings like `"en-US"`.
+*
+*See the [Rust documentation for `Locale`](https://docs.rs/icu/latest/icu/locid/struct.Locale.html) for more information.
+*/
 class Locale internal constructor (
     internal val handle: Pointer,
     // These ensure that anything that is borrowed is kept alive and not cleaned
@@ -28,6 +31,8 @@ class Locale internal constructor (
         internal val libClass: Class<LocaleLib> = LocaleLib::class.java
         internal val lib: LocaleLib = Native.load("somelib", libClass)
 
+        /** Construct an [`Locale`] from a locale identifier represented as a string.
+        */
         fun new_(name: String): Locale {
             val (nameMem, nameSlice) = PrimitiveArrayTools.readUtf8(name)
 

tool/src/kotlin/formatter.rs

@@ -1,8 +1,9 @@
 use diplomat_core::hir::{
     self,
     borrowing_param::{LifetimeEdge, LifetimeEdgeKind},
-    FloatType, IntSizeType, IntType, LifetimeEnv, MaybeStatic, PrimitiveType, Slice,
-    StringEncoding, StructPathLike, TraitId, TyPosition, Type, TypeContext, TypeId,
+    Docs, DocsUrlGenerator, FloatType, IntSizeType, IntType, LifetimeEnv, MaybeStatic,
+    PrimitiveType, Slice, StringEncoding, StructPathLike, TraitId, TyPosition, Type, TypeContext,
+    TypeId,
 };
 use heck::ToLowerCamelCase;
 use std::{borrow::Cow, iter::once};
@@ -11,6 +12,8 @@ use std::{borrow::Cow, iter::once};
 pub(super) struct KotlinFormatter<'tcx> {
     tcx: &'tcx TypeContext,
     strip_prefix: Option<String>,
+    /// For generating doc.rs links
+    docs_url_gen: &'tcx DocsUrlGenerator,
 }
 
 const INVALID_METHOD_NAMES: &[&str] = &[
@@ -19,8 +22,16 @@ const INVALID_METHOD_NAMES: &[&str] = &[
 const DISALLOWED_CORE_TYPES: &[&str] = &["Object", "String"];
 
 impl<'tcx> KotlinFormatter<'tcx> {
-    pub fn new(tcx: &'tcx TypeContext, strip_prefix: Option<String>) -> Self {
-        Self { tcx, strip_prefix }
+    pub fn new(
+        tcx: &'tcx TypeContext,
+        strip_prefix: Option<String>,
+        docs_url_gen: &'tcx DocsUrlGenerator,
+    ) -> Self {
+        Self {
+            tcx,
+            strip_prefix,
+            docs_url_gen,
+        }
     }
 
     pub fn fmt_void(&self) -> &'static str {
@@ -44,6 +55,13 @@ impl<'tcx> KotlinFormatter<'tcx> {
         "String"
     }
 
+    pub fn fmt_docs(&self, docs: &Docs) -> String {
+        docs.to_markdown(self.docs_url_gen)
+            .trim()
+            .replace('\n', "\n*")
+            .replace(" \n", "\n")
+    }
+
     pub fn fmt_primitive_slice(&self, ty: PrimitiveType) -> String {
         format!("{}Array", self.fmt_primitive_as_kt(ty))
     }
@@ -450,7 +468,9 @@ pub mod test {
             }
         };
         let tcx = new_tcx(tk_stream);
-        let formatter = KotlinFormatter::new(&tcx, None);
+        let docs_urls = std::collections::HashMap::new();
+        let docs_generator = &diplomat_core::hir::DocsUrlGenerator::with_base_urls(None, docs_urls);
+        let formatter = KotlinFormatter::new(&tcx, None, docs_generator);
         let opaques = tcx.opaques();
         assert!(!opaques.is_empty());
         let mut all_types = tcx.all_types();