Add book entry

Author: BenFordTytherington

book/src/bridge/attributes.md

@@ -43,3 +43,8 @@ For [`#[qproperty]`](./extern_rustqt.md#properties), a CXX or Rust name can be p
 The `#[auto_cxx_name]` and `#[auto_rust_name]` attributes can be used to automatically rename cxx and rust names.
 These are placed at a block level on `extern "RustQt"` or `extern "C++Qt"` blocks, and will automatically case convert the items inside, unless they specify either a `rust_name` or `cxx_name`.
 By default `#[auto_cxx_name]` will generate a camelCase conversion for`cxx_name` and `#[auto_rust_name]` will generate a snake_case conversion for `rust_name`.
+
+### Automatic wrapping
+
+A fairly common operation is calling a method on the inner rust type, via the `.rust()` accessor. This can be simplified
+with the `#[auto_wrap]` attribute. This will generate a wrapper for your function which accesses the rust method of that name.

crates/cxx-qt-gen/src/generator/naming/qobject.rs

@@ -112,6 +112,14 @@ pub mod tests {
         QObjectNames::from_qobject(&create_parsed_qobject(), &TypeNames::mock()).unwrap()
     }
 
+    /// Used for opaqure objects mocking, adding the QColor type
+    pub fn create_qobjectname_with_qcolor() -> QObjectNames {
+        let mut type_names = TypeNames::mock();
+        type_names.mock_insert("QColor", Some(format_ident!("qobject")), None, None);
+
+        QObjectNames::from_qobject(&create_parsed_qobject(), &type_names).unwrap()
+    }
+
     #[test]
     fn test_parsed_property() {
         let names =

crates/cxx-qt-gen/src/generator/rust/method.rs

@@ -3,17 +3,22 @@
 //
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
-use crate::generator::rust::{get_call_params_tokens, get_params_tokens};
+use crate::generator::rust::{
+    get_call_params_tokens, get_params_tokens, get_params_tokens_qualified,
+};
+use crate::naming::rust::syn_type_cxx_bridge_to_qualified;
+use crate::naming::TypeNames;
 use crate::{
     generator::{naming::qobject::QObjectNames, rust::fragment::GeneratedRustFragment},
     parser::method::ParsedMethod,
 };
 use quote::quote;
-use syn::{parse_quote_spanned, spanned::Spanned, Result};
+use syn::{parse_quote_spanned, spanned::Spanned, Result, ReturnType};
 
 pub fn generate_rust_methods(
     invokables: &[&ParsedMethod],
     qobject_names: &QObjectNames,
+    type_names: &TypeNames,
 ) -> Result<GeneratedRustFragment> {
     let cpp_class_name_rust = &qobject_names.name.rust_unqualified();
 
@@ -31,11 +36,28 @@ pub fn generate_rust_methods(
                 cpp_class_name_rust,
             );
 
+            let parameter_signatures_qualified = get_params_tokens_qualified(
+                invokable.mutable,
+                &invokable.parameters,
+                &qobject_names.name.rust_qualified(),
+                type_names,
+            )?;
+
             let call_parameters = get_call_params_tokens(&invokable.parameters);
 
             let return_type = &invokable.method.sig.output;
+            let qualified_return_type = match return_type {
+                ReturnType::Default => ReturnType::Default,
+                ReturnType::Type(arrow, boxed_type) => {
+                    let ty = boxed_type.as_ref();
+                    let qualified_type = syn_type_cxx_bridge_to_qualified(ty, type_names)?;
+                    ReturnType::Type(*arrow, Box::new(qualified_type))
+                }
+            };
 
             let cfgs = &invokable.cfgs;
+            let docs = &invokable.docs;
+
             let cxx_namespace = qobject_names.namespace_tokens();
 
             let (block_type, block_safety) = if invokable.is_pure {
@@ -56,18 +78,38 @@ pub fn generate_rust_methods(
                 Some(quote! { unsafe })
             };
 
+            let method_safety = if invokable.safe {
+                None
+            } else {
+                Some(quote! { unsafe })
+            };
+
+            let qualified_impl = type_names.rust_qualified(&invokable.qobject_ident)?;
+
+            let inner_fn = if invokable.mutable {
+                quote! { rust_mut() }
+            } else {
+                quote! { rust() }
+            };
+
             let wrapper_fn = if invokable.wrap {
                 vec![parse_quote_spanned! {
                     invokable.method.span() =>
-                    #unsafe_call fn #invokable_ident_rust(#parameter_signatures) #return_type {
-                        self.rust().#invokable_ident_rust(#call_parameters)
+                    #(#cfgs)*
+                    impl #qualified_impl {
+                        #(#docs)*
+                        pub #method_safety fn #invokable_ident_rust(#parameter_signatures_qualified) #qualified_return_type {
+                            use cxx_qt::CxxQtType;
+
+                            self.#inner_fn.#invokable_ident_rust(#call_parameters)
+                        }
                     }
                 }]
             } else {
                 vec![]
             };
 
-            GeneratedRustFragment {
+            Ok(GeneratedRustFragment {
                 cxx_mod_contents: vec![parse_quote_spanned! {
                     invokable.method.span() =>
                     // Note: extern "Rust" block does not need to be unsafe
@@ -87,18 +129,21 @@ pub fn generate_rust_methods(
                     }
                 }],
                 cxx_qt_mod_contents: wrapper_fn,
-            }
+            })
         })
-        .collect::<Vec<_>>();
+        .collect::<Result<Vec<_>>>()?;
 
     Ok(GeneratedRustFragment::flatten(generated))
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
+    use quote::format_ident;
 
-    use crate::generator::naming::qobject::tests::create_qobjectname;
+    use crate::generator::naming::qobject::tests::{
+        create_qobjectname, create_qobjectname_with_qcolor,
+    };
     use crate::tests::assert_tokens_eq;
     use syn::{parse_quote, ForeignItemFn};
 
@@ -128,10 +173,18 @@ mod tests {
             ParsedMethod::mock_qinvokable(&method3).make_mutable(),
             ParsedMethod::mock_qinvokable(&method4).make_unsafe(),
         ];
-        let qobject_names = create_qobjectname();
+        let qobject_names = create_qobjectname_with_qcolor();
 
-        let generated =
-            generate_rust_methods(&invokables.iter().collect::<Vec<_>>(), &qobject_names).unwrap();
+        let mut type_names = TypeNames::mock();
+        type_names.mock_insert("QColor", Some(format_ident!("qobject")), None, None);
+        type_names.mock_insert("T", Some(format_ident!("qobject")), None, None);
+
+        let generated = generate_rust_methods(
+            &invokables.iter().collect::<Vec<_>>(),
+            &qobject_names,
+            &type_names,
+        )
+        .unwrap();
 
         assert_eq!(generated.cxx_mod_contents.len(), 4);
         assert_eq!(generated.cxx_qt_mod_contents.len(), 2);
@@ -175,8 +228,12 @@ mod tests {
         assert_tokens_eq(
             &generated.cxx_qt_mod_contents[0],
             quote! {
-                fn opaque_invokable(self: Pin<&mut MyObject>, param: &QColor) -> UniquePtr<QColor> {
-                    self.rust().opaque_invokable(param)
+                impl qobject::MyObject {
+                    pub fn opaque_invokable(self: Pin<&mut qobject::MyObject>, param: &qobject::QColor) -> cxx::UniquePtr<qobject::QColor> {
+                        use cxx_qt::CxxQtType;
+
+                        self.rust_mut().opaque_invokable(param)
+                    }
                 }
             },
         );
@@ -196,8 +253,12 @@ mod tests {
         assert_tokens_eq(
             &generated.cxx_qt_mod_contents[1],
             quote! {
-                unsafe fn unsafe_invokable(self:&MyObject, param: *mut T) -> *mut T {
-                    self.rust().unsafe_invokable(param)
+                impl qobject::MyObject {
+                    pub unsafe fn unsafe_invokable(self:&qobject::MyObject, param: *mut qobject::T) -> *mut qobject::T {
+                        use cxx_qt::CxxQtType;
+
+                        self.rust().unsafe_invokable(param)
+                    }
                 }
             },
         );

crates/cxx-qt-gen/src/generator/rust/mod.rs

@@ -16,11 +16,13 @@ pub mod signals;
 pub mod threading;
 
 use crate::generator::{rust::fragment::GeneratedRustFragment, structuring};
+use crate::naming::rust::syn_type_cxx_bridge_to_qualified;
+use crate::naming::TypeNames;
 use crate::parser::cxxqtdata::ParsedCxxQtData;
 use crate::parser::{parameter::ParsedFunctionParameter, Parser};
 use proc_macro2::{Ident, TokenStream};
 use quote::quote;
-use syn::{parse_quote, Item, ItemMod, Result};
+use syn::{parse_quote, Item, ItemMod, Path, Result};
 
 /// Representation of the generated Rust code for a QObject
 pub struct GeneratedRustBlocks {
@@ -146,6 +148,33 @@ pub fn get_params_tokens(
     }
 }
 
+/// Return the [TokenStream] of the parsed parameters, with self type qualified for use in generation
+pub fn get_params_tokens_qualified(
+    mutable: bool,
+    parameters: &[ParsedFunctionParameter],
+    class_name_path: &Path,
+    type_names: &TypeNames,
+) -> Result<TokenStream> {
+    let struct_sig = if mutable {
+        quote! { Pin<&mut #class_name_path> }
+    } else {
+        quote! { &#class_name_path }
+    };
+    if parameters.is_empty() {
+        Ok(quote! { self: #struct_sig })
+    } else {
+        let parameters = parameters
+            .iter()
+            .map(|parameter| {
+                let ident = &parameter.ident;
+                let qualified_ty = &syn_type_cxx_bridge_to_qualified(&parameter.ty, type_names)?;
+                Ok(quote! { #ident: #qualified_ty })
+            })
+            .collect::<Result<Vec<TokenStream>>>()?;
+        Ok(quote! { self: #struct_sig, #(#parameters),* })
+    }
+}
+
 /// Return the [TokenStream] of the parsed parameters, which would be used to call the fn, for use in generation
 pub fn get_call_params_tokens(parameters: &[ParsedFunctionParameter]) -> TokenStream {
     if parameters.is_empty() {

crates/cxx-qt-gen/src/generator/rust/qobject.rs

@@ -35,7 +35,7 @@ impl GeneratedRustFragment {
                 type_names,
                 structured_qobject,
             )?,
-            generate_rust_methods(&structured_qobject.methods, &qobject_names)?,
+            generate_rust_methods(&structured_qobject.methods, &qobject_names, type_names)?,
             inherit::generate(&qobject_names, &structured_qobject.inherited_methods)?,
             generate_rust_signals(&structured_qobject.signals, &qobject_names, type_names)?,
         ];

crates/cxx-qt-gen/src/parser/method.rs

@@ -2,7 +2,7 @@
 // SPDX-FileContributor: Andrew Hayzen <[email protected]>
 //
 // SPDX-License-Identifier: MIT OR Apache-2.0
-use crate::parser::CaseConversion;
+use crate::parser::{extract_docs, CaseConversion};
 use crate::{
     naming::Name,
     parser::{extract_cfgs, parameter::ParsedFunctionParameter, require_attributes},
@@ -61,10 +61,10 @@ pub struct ParsedMethod {
     pub is_pure: bool,
     /// Whether to auto generate a wrapper for this method outside the bridge
     pub wrap: bool,
-    // No docs field since the docs should be on the method implementation outside the bridge
-    // This means any docs on the bridge declaration would be ignored
     /// Cfgs for the method
     pub cfgs: Vec<Attribute>,
+    /// Docs for the method, for passing onto the auto_wrap generated methods
+    pub docs: Vec<Attribute>,
     /// Whether the block containing the method is safe or unsafe
     pub unsafe_block: bool,
 }
@@ -126,6 +126,7 @@ impl ParsedMethod {
         let fields = MethodFields::parse(method, auto_case)?;
         let attrs = require_attributes(&fields.method.attrs, &Self::ALLOWED_ATTRS)?;
         let cfgs = extract_cfgs(&fields.method.attrs);
+        let docs = extract_docs(&fields.method.attrs);
 
         // Determine if the method is invokable
         let is_qinvokable = attrs.contains_key("qinvokable");
@@ -140,6 +141,7 @@ impl ParsedMethod {
             is_pure,
             wrap,
             cfgs,
+            docs,
             unsafe_block,
         })
     }

crates/cxx-qt-gen/test_outputs/passthrough_and_naming.rs

@@ -780,8 +780,11 @@ cxx_qt::static_assertions::assert_eq_size!(
     cxx_qt::signalhandler::CxxQtSignalHandler<SecondObjectCxxQtSignalClosurepropertyNameChanged>,
     [usize; 2]
 );
-unsafe fn my_function(self: &SecondObject, param: i32) {
-    self.rust().my_function(param)
+impl ffi::SecondObject {
+    pub fn my_function(self: &ffi::SecondObject, param: i32) {
+        use cxx_qt::CxxQtType;
+        self.rust().my_function(param)
+    }
 }
 impl ffi::SecondObject {
     #[doc = "Connect the given function pointer to the signal "]

examples/qml_features/rust/src/invokables.rs

@@ -45,6 +45,7 @@ pub mod qobject {
         /// Immutable invokable method that returns the QColor
         #[qinvokable]
         #[cxx_name = "loadColor"]
+        #[auto_wrap]
         fn load_color(self: &RustInvokables) -> QColor;
 
         /// Mutable invokable method that stores a color
@@ -95,11 +96,6 @@ impl Default for RustInvokablesRust {
 
 // ANCHOR: book_invokable_impl
 impl qobject::RustInvokables {
-    /// Immutable invokable method that returns the QColor
-    pub fn load_color(&self) -> QColor {
-        self.as_qcolor()
-    }
-
     /// Mutable invokable method that stores a color
     pub fn store_color(self: Pin<&mut Self>, red: f32, green: f32, blue: f32) {
         self.store_helper(red, green, blue);
@@ -145,7 +141,7 @@ impl qobject::RustInvokables {
 
 impl RustInvokablesRust {
     /// Immutable Rust context method that returns the QColor
-    pub fn as_qcolor(&self) -> QColor {
+    pub fn load_color(&self) -> QColor {
         QColor::from_rgb(
             (self.red * 255.0).round() as i32,
             (self.green * 255.0).round() as i32,