Merge "floss: Add rustdoc for dbus_projection crate"

}

/// 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();

//! 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;

    }

}

/// 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) => {