floss: Add rustdoc for dbus_projection crate
Bug: 197783754
Tag: #floss
Test: manual - Generate doc on Linux with `rust doc`.
Change-Id: Ibb33cc00b27d80c2e8f13a5725a8a336f27c12da
diff --git a/system/gd/rust/linux/dbus_projection/dbus_macros/src/lib.rs b/system/gd/rust/linux/dbus_projection/dbus_macros/src/lib.rs
index 9880abb..9f06c5a 100644
--- a/system/gd/rust/linux/dbus_projection/dbus_macros/src/lib.rs
+++ b/system/gd/rust/linux/dbus_projection/dbus_macros/src/lib.rs
@@ -31,6 +31,14 @@
}
/// Generates a function to export a Rust object to D-Bus.
+///
+/// Example:
+/// ```
+/// #[generate_dbus_exporter(export_foo_dbus_obj, "org.example.FooInterface")]
+/// ```
+///
+/// This generates a method called `export_foo_dbus_obj` that will export a Rust object into a
+/// D-Bus object having interface `org.example.FooInterface`.
#[proc_macro_attribute]
pub fn generate_dbus_exporter(attr: TokenStream, item: TokenStream) -> TokenStream {
let ori_item: proc_macro2::TokenStream = item.clone().into();
diff --git a/system/gd/rust/linux/dbus_projection/src/lib.rs b/system/gd/rust/linux/dbus_projection/src/lib.rs
index c222150..060d305 100644
--- a/system/gd/rust/linux/dbus_projection/src/lib.rs
+++ b/system/gd/rust/linux/dbus_projection/src/lib.rs
@@ -1,6 +1,49 @@
//! This crate provides tools to automatically project generic API to D-Bus RPC.
//!
-//! For D-Bus projection to work automatically, the API needs to follow certain restrictions.
+//! For D-Bus projection to work automatically, the API needs to follow certain restrictions:
+//!
+//! * API does not use D-Bus specific features: Signals, Properties, ObjectManager.
+//! * Interfaces (contain Methods) are hosted on statically allocated D-Bus objects.
+//! * When the service needs to notify the client about changes, callback objects are used. The
+//! client can pass a callback object obeying a specified Interface by passing the D-Bus object
+//! path.
+//!
+//! A good example is in
+//! [`manager_service`](https://android.googlesource.com/platform/packages/modules/Bluetooth/system/+/refs/heads/master/gd/rust/linux/mgmt)
+//! crate:
+//!
+//! * Define RPCProxy like in
+//! [here](https://android.googlesource.com/platform/packages/modules/Bluetooth/system/+/refs/heads/master/gd/rust/linux/mgmt/src/lib.rs)
+//! (TODO: We should remove this requirement in the future).
+//! * Generate `DBusArg` trait like in
+//! [here](https://android.googlesource.com/platform/packages/modules/Bluetooth/system/+/refs/heads/master/gd/rust/linux/mgmt/src/bin/btmanagerd/dbus_arg.rs).
+//! This trait is generated by a macro and cannot simply be imported because of Rust's
+//! [Orphan Rule](https://github.com/Ixrec/rust-orphan-rules).
+//! * Define D-Bus-agnostic traits like in
+//! [here](https://android.googlesource.com/platform/packages/modules/Bluetooth/system/+/refs/heads/master/gd/rust/linux/mgmt/src/iface_bluetooth_manager.rs).
+//! These traits can be projected into D-Bus Interfaces on D-Bus objects. A method parameter can
+//! be of a Rust primitive type, structure, enum, or a callback specially typed as
+//! `Box<dyn SomeCallbackTrait + Send>`. Callback traits implement `RPCProxy`.
+//! * Implement the traits like in
+//! [here](https://android.googlesource.com/platform/packages/modules/Bluetooth/system/+/refs/heads/master/gd/rust/linux/mgmt/src/bin/btmanagerd/bluetooth_manager.rs),
+//! also D-Bus-agnostic.
+//! * Define D-Bus projection mappings like in
+//! [here](https://android.googlesource.com/platform/packages/modules/Bluetooth/system/+/refs/heads/master/gd/rust/linux/mgmt/src/bin/btmanagerd/bluetooth_manager_dbus.rs).
+//! * Add [`generate_dbus_exporter`](dbus_macros::generate_dbus_exporter) macro to an `impl` of a
+//! trait.
+//! * Define a method name of each method with [`dbus_method`](dbus_macros::dbus_method) macro.
+//! * Similarly, for callbacks use [`dbus_proxy_obj`](dbus_macros::dbus_proxy_obj) macro to define
+//! the method mappings.
+//! * Rust primitive types can be converted automatically to and from D-Bus types.
+//! * Rust structures require implementations of `DBusArg` for the conversion. This is made easy
+//! with the [`dbus_propmap`](dbus_macros::dbus_propmap) macro.
+//! * Rust enums require implementations of `DBusArg` for the conversion. This is made easy with
+//! the [`impl_dbus_arg_enum`](impl_dbus_arg_enum) macro.
+//! * To project a Rust object to a D-Bus, call the function generated by
+//! [`generate_dbus_exporter`](dbus_macros::generate_dbus_exporter) like in
+//! [here](https://android.googlesource.com/platform/packages/modules/Bluetooth/system/+/refs/heads/master/gd/rust/linux/mgmt/src/bin/btmanagerd/main.rs)
+//! passing in the object path, D-Bus connection, Crossroads object, the Rust object to be
+//! projected, and a [`DisconnectWatcher`](DisconnectWatcher) object.
use dbus::channel::MatchingReceiver;
use dbus::message::MatchRule;
@@ -73,6 +116,9 @@
}
}
+/// Implements `DBusArg` for an enum.
+///
+/// A Rust enum is converted to D-Bus INT32 type.
#[macro_export]
macro_rules! impl_dbus_arg_enum {
($enum_type:ty) => {
