From 4c35acf77808be6e57dbcad6b2079e36c1ba4990 Mon Sep 17 00:00:00 2001 From: Andrew Hayzen Date: Mon, 17 Apr 2023 13:41:58 +0100 Subject: [PATCH 1/7] cxx-qt-gen: generate docs for public generated items Closes #517 --- CHANGELOG.md | 1 + .../src/generator/rust/invokable.rs | 11 ++ .../src/generator/rust/property/getter.rs | 15 +++ .../src/generator/rust/property/mod.rs | 75 +++++++++++ .../src/generator/rust/property/setter.rs | 7 + .../src/generator/rust/property/signal.rs | 8 ++ .../cxx-qt-gen/src/generator/rust/qobject.rs | 13 ++ .../cxx-qt-gen/src/generator/rust/signals.rs | 10 ++ crates/cxx-qt-gen/src/writer/rust/mod.rs | 115 +++++++++++++++- crates/cxx-qt-gen/test_outputs/inheritance.rs | 36 +++++ crates/cxx-qt-gen/test_outputs/invokables.rs | 48 +++++++ .../test_outputs/passthrough_and_naming.rs | 125 ++++++++++++++++++ crates/cxx-qt-gen/test_outputs/properties.rs | 107 +++++++++++++++ crates/cxx-qt-gen/test_outputs/signals.rs | 38 ++++++ 14 files changed, 602 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8d3f501e7..315289568 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Allow associated constants, types and macro invocations within `impl qobject::T` blocks +- Ensure that generated Rust code works when `#![deny(missing_docs)]` is enabled ### Changed diff --git a/crates/cxx-qt-gen/src/generator/rust/invokable.rs b/crates/cxx-qt-gen/src/generator/rust/invokable.rs index 8e0823948..466a42fad 100644 --- a/crates/cxx-qt-gen/src/generator/rust/invokable.rs +++ b/crates/cxx-qt-gen/src/generator/rust/invokable.rs @@ -30,6 +30,7 @@ pub fn generate_rust_invokables( let wrapper_ident_cpp = idents.wrapper.cpp.to_string(); let wrapper_ident_rust = &idents.wrapper.rust; let invokable_ident_rust = &idents.name.rust; + let invokable_ident_rust_str = invokable_ident_rust.to_string(); let original_method = &invokable.method; let cpp_struct = if invokable.mutable { @@ -94,6 +95,8 @@ pub fn generate_rust_invokables( // TODO: not all methods have a wrapper quote! { impl #rust_struct_name_rust { + #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] + #[doc = #invokable_ident_rust_str] pub #has_unsafe fn #wrapper_ident_rust(#parameter_signatures) #return_type { #has_return cpp.#invokable_ident_rust(#(#parameter_names),*); } @@ -194,6 +197,8 @@ mod tests { &generated.cxx_qt_mod_contents[0], quote! { impl MyObject { + #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] + #[doc = "void_invokable"] pub fn void_invokable_wrapper(self: &MyObject, cpp: &MyObjectQt) { cpp.void_invokable(); } @@ -223,6 +228,8 @@ mod tests { &generated.cxx_qt_mod_contents[2], quote! { impl MyObject { + #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] + #[doc = "trivial_invokable"] pub fn trivial_invokable_wrapper(self: &MyObject, cpp: &MyObjectQt, param: i32) -> i32 { return cpp.trivial_invokable(param); } @@ -252,6 +259,8 @@ mod tests { &generated.cxx_qt_mod_contents[4], quote! { impl MyObject { + #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] + #[doc = "opaque_invokable"] pub fn opaque_invokable_wrapper(self: &mut MyObject, cpp: Pin<&mut MyObjectQt>, param: &QColor) -> UniquePtr { return cpp.opaque_invokable(param); } @@ -281,6 +290,8 @@ mod tests { &generated.cxx_qt_mod_contents[6], quote! { impl MyObject { + #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] + #[doc = "unsafe_invokable"] pub unsafe fn unsafe_invokable_wrapper(self: &MyObject, cpp: &MyObjectQt, param: *mut T) -> *mut T { return cpp.unsafe_invokable(param); } diff --git a/crates/cxx-qt-gen/src/generator/rust/property/getter.rs b/crates/cxx-qt-gen/src/generator/rust/property/getter.rs index 522edf56e..b70a272bb 100644 --- a/crates/cxx-qt-gen/src/generator/rust/property/getter.rs +++ b/crates/cxx-qt-gen/src/generator/rust/property/getter.rs @@ -21,6 +21,8 @@ pub fn generate( let getter_rust = &idents.getter.rust; let getter_mutable_rust = &idents.getter_mutable.rust; let ident = &idents.name.rust; + let ident_str = ident.to_string(); + let notify_ident_str = idents.notify.rust.to_string(); RustFragmentPair { cxx_bridge: vec![quote! { @@ -32,6 +34,10 @@ pub fn generate( implementation: vec![ quote! { impl #rust_struct_name_rust { + #[doc = "Getter for the Q_PROPERTY "] + #[doc = #ident_str] + #[doc = "\n"] + #[doc = "This is an internal method used by C++ to retrieve the value of the Q_PROPERTY in the Rust struct"] pub fn #getter_rust<'a>(&'a self, cpp: &'a #cpp_class_name_rust) -> &'a #ty { cpp.#getter_rust() } @@ -39,6 +45,8 @@ pub fn generate( }, quote! { impl #cpp_class_name_rust { + #[doc = "Getter for the Q_PROPERTY "] + #[doc = #ident_str] pub fn #getter_rust(&self) -> &#ty { &self.rust().#ident } @@ -46,6 +54,13 @@ pub fn generate( }, quote! { impl #cpp_class_name_rust { + #[doc = "unsafe getter for the Q_PROPERTY "] + #[doc = #ident_str] + #[doc = "\n"] + #[doc = "This allows for modifying the Q_PROPERTY without calling the property changed Q_SIGNAL"] + #[doc = "\n"] + #[doc = "After modifying the property, make sure to call the corresponding changed signal: "] + #[doc = #notify_ident_str] pub unsafe fn #getter_mutable_rust<'a>(mut self: Pin<&'a mut Self>) -> &'a mut #ty { &mut self.rust_mut().get_unchecked_mut().#ident } diff --git a/crates/cxx-qt-gen/src/generator/rust/property/mod.rs b/crates/cxx-qt-gen/src/generator/rust/property/mod.rs index 46e3a8c4a..52a61bb1c 100644 --- a/crates/cxx-qt-gen/src/generator/rust/property/mod.rs +++ b/crates/cxx-qt-gen/src/generator/rust/property/mod.rs @@ -110,6 +110,10 @@ mod tests { generated.cxx_qt_mod_contents[0], parse_quote! { impl MyObject { + #[doc = "Getter for the Q_PROPERTY "] + #[doc = "trivial_property"] + #[doc = "\n"] + #[doc = "This is an internal method used by C++ to retrieve the value of the Q_PROPERTY in the Rust struct"] pub fn trivial_property<'a>(&'a self, cpp: &'a MyObjectQt) -> &'a i32 { cpp.trivial_property() } @@ -120,6 +124,8 @@ mod tests { generated.cxx_qt_mod_contents[1], parse_quote! { impl MyObjectQt { + #[doc = "Getter for the Q_PROPERTY "] + #[doc = "trivial_property"] pub fn trivial_property(&self) -> &i32 { &self.rust().trivial_property } @@ -130,6 +136,13 @@ mod tests { generated.cxx_qt_mod_contents[2], parse_quote! { impl MyObjectQt { + #[doc = "unsafe getter for the Q_PROPERTY "] + #[doc = "trivial_property"] + #[doc = "\n"] + #[doc = "This allows for modifying the Q_PROPERTY without calling the property changed Q_SIGNAL"] + #[doc = "\n"] + #[doc = "After modifying the property, make sure to call the corresponding changed signal: "] + #[doc = "trivial_property_changed"] pub unsafe fn trivial_property_mut<'a>(mut self: Pin<&'a mut Self>) -> &'a mut i32 { &mut self.rust_mut().get_unchecked_mut().trivial_property } @@ -151,6 +164,10 @@ mod tests { generated.cxx_qt_mod_contents[3], parse_quote! { impl MyObject { + #[doc = "Setter for the Q_PROPERTY "] + #[doc = "trivial_property"] + #[doc = "\n"] + #[doc = "This is an internal method used by C++ to set the value of the Q_PROPERTY in the Rust struct"] pub fn set_trivial_property(&mut self, cpp: Pin<&mut MyObjectQt>, value: i32) { cpp.set_trivial_property(value); } @@ -161,6 +178,8 @@ mod tests { generated.cxx_qt_mod_contents[4], parse_quote! { impl MyObjectQt { + #[doc = "Setter for the Q_PROPERTY "] + #[doc = "trivial_property"] pub fn set_trivial_property(mut self: Pin<&mut Self>, value: i32) { if self.rust().trivial_property == value { return; @@ -179,6 +198,12 @@ mod tests { generated.cxx_mod_contents[2], parse_quote! { unsafe extern "C++" { + #[doc = "Notify signal for the Q_PROPERTY"] + #[doc = "trivial_property"] + #[doc = "\n"] + #[doc = "This can be used to manually notify a change when the unsafe mutable getter,"] + #[doc = "trivial_property_mut"] + #[doc = ", is used."] #[rust_name = "trivial_property_changed"] fn trivialPropertyChanged(self: Pin<&mut MyObjectQt>); } @@ -201,6 +226,10 @@ mod tests { generated.cxx_qt_mod_contents[5], parse_quote! { impl MyObject { + #[doc = "Getter for the Q_PROPERTY "] + #[doc = "opaque_property"] + #[doc = "\n"] + #[doc = "This is an internal method used by C++ to retrieve the value of the Q_PROPERTY in the Rust struct"] pub fn opaque_property<'a>(&'a self, cpp: &'a MyObjectQt) -> &'a UniquePtr { cpp.opaque_property() } @@ -211,6 +240,8 @@ mod tests { generated.cxx_qt_mod_contents[6], parse_quote! { impl MyObjectQt { + #[doc = "Getter for the Q_PROPERTY "] + #[doc = "opaque_property"] pub fn opaque_property(&self) -> &UniquePtr { &self.rust().opaque_property } @@ -221,6 +252,13 @@ mod tests { generated.cxx_qt_mod_contents[7], parse_quote! { impl MyObjectQt { + #[doc = "unsafe getter for the Q_PROPERTY "] + #[doc = "opaque_property"] + #[doc = "\n"] + #[doc = "This allows for modifying the Q_PROPERTY without calling the property changed Q_SIGNAL"] + #[doc = "\n"] + #[doc = "After modifying the property, make sure to call the corresponding changed signal: "] + #[doc = "opaque_property_changed"] pub unsafe fn opaque_property_mut<'a>(mut self: Pin<&'a mut Self>) -> &'a mut UniquePtr { &mut self.rust_mut().get_unchecked_mut().opaque_property } @@ -242,6 +280,10 @@ mod tests { generated.cxx_qt_mod_contents[8], parse_quote! { impl MyObject { + #[doc = "Setter for the Q_PROPERTY "] + #[doc = "opaque_property"] + #[doc = "\n"] + #[doc = "This is an internal method used by C++ to set the value of the Q_PROPERTY in the Rust struct"] pub fn set_opaque_property(&mut self, cpp: Pin<&mut MyObjectQt>, value: UniquePtr) { cpp.set_opaque_property(value); } @@ -252,6 +294,8 @@ mod tests { generated.cxx_qt_mod_contents[9], parse_quote! { impl MyObjectQt { + #[doc = "Setter for the Q_PROPERTY "] + #[doc = "opaque_property"] pub fn set_opaque_property(mut self: Pin<&mut Self>, value: UniquePtr) { if self.rust().opaque_property == value { return; @@ -270,6 +314,12 @@ mod tests { generated.cxx_mod_contents[5], parse_quote! { unsafe extern "C++" { + #[doc = "Notify signal for the Q_PROPERTY"] + #[doc = "opaque_property"] + #[doc = "\n"] + #[doc = "This can be used to manually notify a change when the unsafe mutable getter,"] + #[doc = "opaque_property_mut"] + #[doc = ", is used."] #[rust_name = "opaque_property_changed"] fn opaquePropertyChanged(self: Pin<&mut MyObjectQt>); } @@ -292,6 +342,10 @@ mod tests { generated.cxx_qt_mod_contents[10], parse_quote! { impl MyObject { + #[doc = "Getter for the Q_PROPERTY "] + #[doc = "unsafe_property"] + #[doc = "\n"] + #[doc = "This is an internal method used by C++ to retrieve the value of the Q_PROPERTY in the Rust struct"] pub fn unsafe_property<'a>(&'a self, cpp: &'a MyObjectQt) -> &'a *mut T { cpp.unsafe_property() } @@ -302,6 +356,8 @@ mod tests { generated.cxx_qt_mod_contents[11], parse_quote! { impl MyObjectQt { + #[doc = "Getter for the Q_PROPERTY "] + #[doc = "unsafe_property"] pub fn unsafe_property(&self) -> &*mut T { &self.rust().unsafe_property } @@ -312,6 +368,13 @@ mod tests { generated.cxx_qt_mod_contents[12], parse_quote! { impl MyObjectQt { + #[doc = "unsafe getter for the Q_PROPERTY "] + #[doc = "unsafe_property"] + #[doc = "\n"] + #[doc = "This allows for modifying the Q_PROPERTY without calling the property changed Q_SIGNAL"] + #[doc = "\n"] + #[doc = "After modifying the property, make sure to call the corresponding changed signal: "] + #[doc = "unsafe_property_changed"] pub unsafe fn unsafe_property_mut<'a>(mut self: Pin<&'a mut Self>) -> &'a mut *mut T { &mut self.rust_mut().get_unchecked_mut().unsafe_property } @@ -333,6 +396,10 @@ mod tests { generated.cxx_qt_mod_contents[13], parse_quote! { impl MyObject { + #[doc = "Setter for the Q_PROPERTY "] + #[doc = "unsafe_property"] + #[doc = "\n"] + #[doc = "This is an internal method used by C++ to set the value of the Q_PROPERTY in the Rust struct"] pub fn set_unsafe_property(&mut self, cpp: Pin<&mut MyObjectQt>, value: *mut T) { cpp.set_unsafe_property(value); } @@ -343,6 +410,8 @@ mod tests { generated.cxx_qt_mod_contents[14], parse_quote! { impl MyObjectQt { + #[doc = "Setter for the Q_PROPERTY "] + #[doc = "unsafe_property"] pub fn set_unsafe_property(mut self: Pin<&mut Self>, value: *mut T) { if self.rust().unsafe_property == value { return; @@ -361,6 +430,12 @@ mod tests { generated.cxx_mod_contents[8], parse_quote! { unsafe extern "C++" { + #[doc = "Notify signal for the Q_PROPERTY"] + #[doc = "unsafe_property"] + #[doc = "\n"] + #[doc = "This can be used to manually notify a change when the unsafe mutable getter,"] + #[doc = "unsafe_property_mut"] + #[doc = ", is used."] #[rust_name = "unsafe_property_changed"] fn unsafePropertyChanged(self: Pin<&mut MyObjectQt>); } diff --git a/crates/cxx-qt-gen/src/generator/rust/property/setter.rs b/crates/cxx-qt-gen/src/generator/rust/property/setter.rs index 5d39c2475..9db646969 100644 --- a/crates/cxx-qt-gen/src/generator/rust/property/setter.rs +++ b/crates/cxx-qt-gen/src/generator/rust/property/setter.rs @@ -20,6 +20,7 @@ pub fn generate( let setter_cpp = idents.setter.cpp.to_string(); let setter_rust = &idents.setter.rust; let ident = &idents.name.rust; + let ident_str = ident.to_string(); let notify_ident = &idents.notify.rust; // Determine if unsafe is required due to an unsafe type @@ -39,6 +40,10 @@ pub fn generate( implementation: vec![ quote! { impl #rust_struct_name_rust { + #[doc = "Setter for the Q_PROPERTY "] + #[doc = #ident_str] + #[doc = "\n"] + #[doc = "This is an internal method used by C++ to set the value of the Q_PROPERTY in the Rust struct"] pub fn #setter_rust(&mut self, cpp: Pin<&mut #cpp_class_name_rust>, value: #ty) { cpp.#setter_rust(value); } @@ -46,6 +51,8 @@ pub fn generate( }, quote! { impl #cpp_class_name_rust { + #[doc = "Setter for the Q_PROPERTY "] + #[doc = #ident_str] pub fn #setter_rust(mut self: Pin<&mut Self>, value: #ty) { if self.rust().#ident == value { // don't want to set the value again and reemit the signal, diff --git a/crates/cxx-qt-gen/src/generator/rust/property/signal.rs b/crates/cxx-qt-gen/src/generator/rust/property/signal.rs index c86b6dec1..7f1e6d784 100644 --- a/crates/cxx-qt-gen/src/generator/rust/property/signal.rs +++ b/crates/cxx-qt-gen/src/generator/rust/property/signal.rs @@ -13,10 +13,18 @@ pub fn generate(idents: &QPropertyName, qobject_idents: &QObjectName) -> RustFra let cpp_class_name_rust = &qobject_idents.cpp_class.rust; let notify_cpp = &idents.notify.cpp; let notify_rust = idents.notify.rust.to_string(); + let ident_str = idents.name.rust.to_string(); + let getter_mutable_rust_str = idents.getter_mutable.rust.to_string(); RustFragmentPair { cxx_bridge: vec![quote! { unsafe extern "C++" { + #[doc = "Notify signal for the Q_PROPERTY"] + #[doc = #ident_str] + #[doc = "\n"] + #[doc = "This can be used to manually notify a change when the unsafe mutable getter,"] + #[doc = #getter_mutable_rust_str] + #[doc = ", is used."] #[rust_name = #notify_rust] fn #notify_cpp(self: Pin<&mut #cpp_class_name_rust>); } diff --git a/crates/cxx-qt-gen/src/generator/rust/qobject.rs b/crates/cxx-qt-gen/src/generator/rust/qobject.rs index dda5e4493..63025f5c9 100644 --- a/crates/cxx-qt-gen/src/generator/rust/qobject.rs +++ b/crates/cxx-qt-gen/src/generator/rust/qobject.rs @@ -157,10 +157,17 @@ fn generate_qobject_definitions( let cpp_class_name_rust = &qobject_idents.cpp_class.rust; let rust_struct_name_cpp = &qobject_idents.rust_struct.cpp.to_string(); let rust_struct_name_rust = &qobject_idents.rust_struct.rust; + let rust_struct_name_rust_str = rust_struct_name_rust.to_string(); let fragment = RustFragmentPair { cxx_bridge: vec![ quote! { unsafe extern "C++" { + #[doc = "The C++ type for the QObject "] + #[doc = #rust_struct_name_rust_str] + #[doc = "\n"] + #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "\n"] + #[doc = "See the book for more information: "] #[cxx_name = #cpp_class_name_cpp] type #cpp_class_name_rust; } @@ -254,6 +261,12 @@ mod tests { &rust.blocks.cxx_mod_contents[0], quote! { unsafe extern "C++" { + #[doc = "The C++ type for the QObject "] + #[doc = "MyObject"] + #[doc = "\n"] + #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "\n"] + #[doc = "See the book for more information: "] #[cxx_name = "MyObject"] type MyObjectQt; } diff --git a/crates/cxx-qt-gen/src/generator/rust/signals.rs b/crates/cxx-qt-gen/src/generator/rust/signals.rs index ac8741a92..812c7afad 100644 --- a/crates/cxx-qt-gen/src/generator/rust/signals.rs +++ b/crates/cxx-qt-gen/src/generator/rust/signals.rs @@ -98,8 +98,14 @@ pub fn generate_rust_signals( } // Add the Rust method using the enum to call the methods + let qobject_ident_str = qobject_idents.rust_struct.rust.to_string(); + let signal_enum_ident_str = signal_enum_ident.to_string(); generated.cxx_qt_mod_contents.push(syn::parse2(quote! { impl #cpp_class_name_rust { + #[doc = "Emit the signal from the enum "] + #[doc = #signal_enum_ident_str] + #[doc = " on the QObject "] + #[doc = #qobject_ident_str] pub fn emit(self: Pin<&mut Self>, signal: #signal_enum_ident) { match signal { #(#signal_matches),* @@ -214,6 +220,10 @@ mod tests { &generated.cxx_qt_mod_contents[1], quote! { impl MyObjectQt { + #[doc = "Emit the signal from the enum "] + #[doc = "MySignals"] + #[doc = " on the QObject "] + #[doc = "MyObject"] pub fn emit(self: Pin<&mut Self>, signal: MySignals) { match signal { MySignals::Ready {} => { self.emit_ready() }, diff --git a/crates/cxx-qt-gen/src/writer/rust/mod.rs b/crates/cxx-qt-gen/src/writer/rust/mod.rs index f6dba2871..995c7a3e3 100644 --- a/crates/cxx-qt-gen/src/writer/rust/mod.rs +++ b/crates/cxx-qt-gen/src/writer/rust/mod.rs @@ -21,6 +21,7 @@ fn mangle(name: &str, object: &Ident) -> Ident { /// Return common blocks for CXX bridge which the C++ writer adds as well fn cxx_bridge_common_blocks(qobject: &GeneratedRustQObject) -> Vec { let cpp_struct_ident = &qobject.cpp_struct_ident; + let cpp_struct_ident_str = cpp_struct_ident.to_string(); let rust_struct_ident = &qobject.rust_struct_ident; let cxx_qt_thread_ident = &qobject.cxx_qt_thread_ident; let cxx_qt_thread_queued_fn_ident = &qobject.cxx_qt_thread_queued_fn_ident; @@ -32,17 +33,21 @@ fn cxx_bridge_common_blocks(qobject: &GeneratedRustQObject) -> Vec vec![ quote! { unsafe extern "C++" { - // Specialised version of CxxQtThread - // - // CXX doesn't support having generic types in the function yet - // so we cannot have CxxQtThread in cxx-qt-lib and then use that here - // For now we use a type alias on C++ then use it like a normal type here - // https://github.com/dtolnay/cxx/issues/683 + /// Specialised version of CxxQtThread, which can be moved into other threads. + /// + /// CXX doesn't support having generic types in the function yet + /// so we cannot have CxxQtThread in cxx-qt-lib and then use that here + /// For now we use a type alias in C++ then use it like a normal type here + /// https://github.com/dtolnay/cxx/issues/683 type #cxx_qt_thread_ident; + /// Retrieve an immutable reference to the Rust struct backing this C++ object #[cxx_name = "unsafeRust"] fn rust(self: &#cpp_struct_ident) -> &#rust_struct_ident; + /// Create an instance of a CxxQtThread + /// + /// This allows for queueing closures onto the Qt event loop from a background thread. #[cxx_name = "qtThread"] fn qt_thread(self: &#cpp_struct_ident) -> UniquePtr<#cxx_qt_thread_ident>; @@ -56,6 +61,9 @@ fn cxx_bridge_common_blocks(qobject: &GeneratedRustQObject) -> Vec arg: Box<#cxx_qt_thread_queued_fn_ident>, ) -> Result<()>; + #[doc = "Generated CXX-Qt method which creates a new"] + #[doc = #cpp_struct_ident_str] + #[doc = "as a UniquePtr with no parent in Qt"] #[rust_name = #new_cpp_obj_str] #[namespace = #namespace_internals] fn newCppObject() -> UniquePtr<#cpp_struct_ident>; @@ -63,6 +71,9 @@ fn cxx_bridge_common_blocks(qobject: &GeneratedRustQObject) -> Vec }, quote! { extern "C++" { + /// Retrieve a mutable reference to the Rust struct backing this C++ object + /// + /// This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually. #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut #cpp_struct_ident>) -> Pin<&mut #rust_struct_ident>; } @@ -94,6 +105,7 @@ fn cxx_qt_common_blocks(qobject: &GeneratedRustQObject) -> Vec { }, quote! { impl #cxx_qt_thread_ident { + /// Queue the given closure onto the Qt event loop for this QObject pub fn queue(&self, f: F) -> std::result::Result<(), cxx::Exception> where F: FnOnce(std::pin::Pin<&mut #cpp_struct_ident>), @@ -115,6 +127,7 @@ fn cxx_qt_common_blocks(qobject: &GeneratedRustQObject) -> Vec { } }, quote! { + /// Generated CXX-Qt thread helper for a QObject pub struct #cxx_qt_thread_queued_fn_ident { // An opaque Rust type is required to be Sized. // https://github.com/dtolnay/cxx/issues/665 @@ -122,6 +135,7 @@ fn cxx_qt_common_blocks(qobject: &GeneratedRustQObject) -> Vec { } }, quote! { + /// Generated CXX-Qt method which creates a boxed rust struct of a QObject pub fn #create_rs_ident() -> std::boxed::Box<#rust_struct_ident> { std::default::Default::default() } @@ -178,12 +192,22 @@ pub fn write_rust(generated: &GeneratedRustBlocks) -> TokenStream { // Add the type alias to the C++ struct let cpp_struct_ident = &qobject.cpp_struct_ident; let rust_struct_ident = &qobject.rust_struct_ident; - qobject_types.push(quote! { pub type #rust_struct_ident = super::#cpp_struct_ident; }) + let rust_struct_ident_str = rust_struct_ident.to_string(); + qobject_types.push(quote! { + #[doc = "The C++ type for the QObject "] + #[doc = #rust_struct_ident_str] + #[doc = "\n"] + #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "\n"] + #[doc = "See the book for more information: "] + pub type #rust_struct_ident = super::#cpp_struct_ident; + }) } // Create the qobject block for the type alias cxx_qt_mod_contents.push( syn::parse2(quote! { + /// Generated CXX-Qt module containing type alias to the C++ type of the QObjects pub mod qobject { #(#qobject_types)* } @@ -397,11 +421,21 @@ mod tests { } unsafe extern "C++" { + /// Specialised version of CxxQtThread, which can be moved into other threads. + /// + /// CXX doesn't support having generic types in the function yet + /// so we cannot have CxxQtThread in cxx-qt-lib and then use that here + /// For now we use a type alias in C++ then use it like a normal type here + /// https://github.com/dtolnay/cxx/issues/683 type MyObjectCxxQtThread; + /// Retrieve an immutable reference to the Rust struct backing this C++ object #[cxx_name = "unsafeRust"] fn rust(self: &MyObjectQt) -> &MyObject; + /// Create an instance of a CxxQtThread + /// + /// This allows for queueing closures onto the Qt event loop from a background thread. #[cxx_name = "qtThread"] fn qt_thread(self: &MyObjectQt) -> UniquePtr; @@ -412,12 +446,18 @@ mod tests { arg: Box, ) -> Result<()>; + #[doc = "Generated CXX-Qt method which creates a new"] + #[doc = "MyObjectQt"] + #[doc = "as a UniquePtr with no parent in Qt"] #[rust_name = "new_cpp_object_my_object_qt"] #[namespace = "cxx_qt::my_object::cxx_qt_my_object"] fn newCppObject() -> UniquePtr; } extern "C++" { + /// Retrieve a mutable reference to the Rust struct backing this C++ object + /// + /// This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually. #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut MyObjectQt>) -> Pin<&mut MyObject>; } @@ -453,6 +493,7 @@ mod tests { unsafe impl Send for MyObjectCxxQtThread {} impl MyObjectCxxQtThread { + /// Queue the given closure onto the Qt event loop for this QObject pub fn queue(&self, f: F) -> std::result::Result<(), cxx::Exception> where F: FnOnce(std::pin::Pin<&mut MyObjectQt>), @@ -470,15 +511,24 @@ mod tests { } } + /// Generated CXX-Qt thread helper for a QObject pub struct MyObjectCxxQtThreadQueuedFn { inner: std::boxed::Box) + Send>, } + /// Generated CXX-Qt method which creates a boxed rust struct of a QObject pub fn create_rs_my_object() -> std::boxed::Box { std::default::Default::default() } + /// Generated CXX-Qt module containing type alias to the C++ type of the QObjects pub mod qobject { + #[doc = "The C++ type for the QObject "] + #[doc = "MyObject"] + #[doc = "\n"] + #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "\n"] + #[doc = "See the book for more information: "] pub type MyObject = super::MyObjectQt; } } @@ -514,11 +564,21 @@ mod tests { } unsafe extern "C++" { + /// Specialised version of CxxQtThread, which can be moved into other threads. + /// + /// CXX doesn't support having generic types in the function yet + /// so we cannot have CxxQtThread in cxx-qt-lib and then use that here + /// For now we use a type alias in C++ then use it like a normal type here + /// https://github.com/dtolnay/cxx/issues/683 type FirstObjectCxxQtThread; + /// Retrieve an immutable reference to the Rust struct backing this C++ object #[cxx_name = "unsafeRust"] fn rust(self: &FirstObjectQt) -> &FirstObject; + /// Create an instance of a CxxQtThread + /// + /// This allows for queueing closures onto the Qt event loop from a background thread. #[cxx_name = "qtThread"] fn qt_thread(self: &FirstObjectQt) -> UniquePtr; @@ -529,12 +589,18 @@ mod tests { arg: Box, ) -> Result<()>; + #[doc = "Generated CXX-Qt method which creates a new"] + #[doc = "FirstObjectQt"] + #[doc = "as a UniquePtr with no parent in Qt"] #[rust_name = "new_cpp_object_first_object_qt"] #[namespace = "cxx_qt::cxx_qt_first_object"] fn newCppObject() -> UniquePtr; } extern "C++" { + /// Retrieve a mutable reference to the Rust struct backing this C++ object + /// + /// This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually. #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut FirstObjectQt>) -> Pin<&mut FirstObject>; } @@ -558,11 +624,21 @@ mod tests { } unsafe extern "C++" { + /// Specialised version of CxxQtThread, which can be moved into other threads. + /// + /// CXX doesn't support having generic types in the function yet + /// so we cannot have CxxQtThread in cxx-qt-lib and then use that here + /// For now we use a type alias in C++ then use it like a normal type here + /// https://github.com/dtolnay/cxx/issues/683 type SecondObjectCxxQtThread; + /// Retrieve an immutable reference to the Rust struct backing this C++ object #[cxx_name = "unsafeRust"] fn rust(self: &SecondObjectQt) -> &SecondObject; + /// Create an instance of a CxxQtThread + /// + /// This allows for queueing closures onto the Qt event loop from a background thread. #[cxx_name = "qtThread"] fn qt_thread(self: &SecondObjectQt) -> UniquePtr; @@ -573,12 +649,18 @@ mod tests { arg: Box, ) -> Result<()>; + #[doc = "Generated CXX-Qt method which creates a new"] + #[doc = "SecondObjectQt"] + #[doc = "as a UniquePtr with no parent in Qt"] #[rust_name = "new_cpp_object_second_object_qt"] #[namespace = "cxx_qt::cxx_qt_second_object"] fn newCppObject() -> UniquePtr; } extern "C++" { + /// Retrieve a mutable reference to the Rust struct backing this C++ object + /// + /// This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually. #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut SecondObjectQt>) -> Pin<&mut SecondObject>; } @@ -614,6 +696,7 @@ mod tests { unsafe impl Send for FirstObjectCxxQtThread {} impl FirstObjectCxxQtThread { + /// Queue the given closure onto the Qt event loop for this QObject pub fn queue(&self, f: F) -> std::result::Result<(), cxx::Exception> where F: FnOnce(std::pin::Pin<&mut FirstObjectQt>), @@ -631,10 +714,12 @@ mod tests { } } + /// Generated CXX-Qt thread helper for a QObject pub struct FirstObjectCxxQtThreadQueuedFn { inner: std::boxed::Box) + Send>, } + /// Generated CXX-Qt method which creates a boxed rust struct of a QObject pub fn create_rs_first_object() -> std::boxed::Box { std::default::Default::default() } @@ -651,6 +736,7 @@ mod tests { unsafe impl Send for SecondObjectCxxQtThread {} impl SecondObjectCxxQtThread { + /// Queue the given closure onto the Qt event loop for this QObject pub fn queue(&self, f: F) -> std::result::Result<(), cxx::Exception> where F: FnOnce(std::pin::Pin<&mut SecondObjectQt>), @@ -668,16 +754,31 @@ mod tests { } } + /// Generated CXX-Qt thread helper for a QObject pub struct SecondObjectCxxQtThreadQueuedFn { inner: std::boxed::Box) + Send>, } + /// Generated CXX-Qt method which creates a boxed rust struct of a QObject pub fn create_rs_second_object() -> std::boxed::Box { std::default::Default::default() } + /// Generated CXX-Qt module containing type alias to the C++ type of the QObjects pub mod qobject { + #[doc = "The C++ type for the QObject "] + #[doc = "FirstObject"] + #[doc = "\n"] + #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "\n"] + #[doc = "See the book for more information: "] pub type FirstObject = super::FirstObjectQt; + #[doc = "The C++ type for the QObject "] + #[doc = "SecondObject"] + #[doc = "\n"] + #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "\n"] + #[doc = "See the book for more information: "] pub type SecondObject = super::SecondObjectQt; } } diff --git a/crates/cxx-qt-gen/test_outputs/inheritance.rs b/crates/cxx-qt-gen/test_outputs/inheritance.rs index 1ac66b300..f5b174b49 100644 --- a/crates/cxx-qt-gen/test_outputs/inheritance.rs +++ b/crates/cxx-qt-gen/test_outputs/inheritance.rs @@ -16,6 +16,12 @@ mod inheritance { include!("cxx-qt-gen/inheritance.cxxqt.h"); } unsafe extern "C++" { + #[doc = "The C++ type for the QObject "] + #[doc = "MyObject"] + #[doc = "\n"] + #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "\n"] + #[doc = "See the book for more information: "] #[cxx_name = "MyObject"] type MyObjectQt; @@ -46,9 +52,19 @@ mod inheritance { unsafe fn fetch_more(self: Pin<&mut MyObjectQt>, index: &QModelIndex); } unsafe extern "C++" { + #[doc = r" Specialised version of CxxQtThread, which can be moved into other threads."] + #[doc = r""] + #[doc = r" CXX doesn't support having generic types in the function yet"] + #[doc = r" so we cannot have CxxQtThread in cxx-qt-lib and then use that here"] + #[doc = r" For now we use a type alias in C++ then use it like a normal type here"] + #[doc = r" https://github.com/dtolnay/cxx/issues/683"] type MyObjectCxxQtThread; + #[doc = r" Retrieve an immutable reference to the Rust struct backing this C++ object"] #[cxx_name = "unsafeRust"] fn rust(self: &MyObjectQt) -> &MyObject; + #[doc = r" Create an instance of a CxxQtThread"] + #[doc = r""] + #[doc = r" This allows for queueing closures onto the Qt event loop from a background thread."] #[cxx_name = "qtThread"] fn qt_thread(self: &MyObjectQt) -> UniquePtr; #[cxx_name = "queue"] @@ -57,11 +73,17 @@ mod inheritance { func: fn(Pin<&mut MyObjectQt>, Box), arg: Box, ) -> Result<()>; + #[doc = "Generated CXX-Qt method which creates a new"] + #[doc = "MyObjectQt"] + #[doc = "as a UniquePtr with no parent in Qt"] #[rust_name = "new_cpp_object_my_object_qt"] #[namespace = "cxx_qt_my_object"] fn newCppObject() -> UniquePtr; } extern "C++" { + #[doc = r" Retrieve a mutable reference to the Rust struct backing this C++ object"] + #[doc = r""] + #[doc = r" This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually."] #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut MyObjectQt>) -> Pin<&mut MyObject>; } @@ -100,6 +122,8 @@ mod cxx_qt_inheritance { } } impl MyObject { + #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] + #[doc = "data"] pub fn data_wrapper( self: &MyObject, cpp: &MyObjectQt, @@ -115,6 +139,8 @@ mod cxx_qt_inheritance { } } impl MyObject { + #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] + #[doc = "has_children"] pub fn has_children_wrapper( self: &MyObject, cpp: &MyObjectQt, @@ -130,6 +156,7 @@ mod cxx_qt_inheritance { } unsafe impl Send for MyObjectCxxQtThread {} impl MyObjectCxxQtThread { + #[doc = r" Queue the given closure onto the Qt event loop for this QObject"] pub fn queue(&self, f: F) -> std::result::Result<(), cxx::Exception> where F: FnOnce(std::pin::Pin<&mut MyObjectQt>), @@ -148,13 +175,22 @@ mod cxx_qt_inheritance { self.queue_boxed_fn(func, std::boxed::Box::new(arg)) } } + #[doc = r" Generated CXX-Qt thread helper for a QObject"] pub struct MyObjectCxxQtThreadQueuedFn { inner: std::boxed::Box) + Send>, } + #[doc = r" Generated CXX-Qt method which creates a boxed rust struct of a QObject"] pub fn create_rs_my_object() -> std::boxed::Box { std::default::Default::default() } + #[doc = r" Generated CXX-Qt module containing type alias to the C++ type of the QObjects"] pub mod qobject { + #[doc = "The C++ type for the QObject "] + #[doc = "MyObject"] + #[doc = "\n"] + #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "\n"] + #[doc = "See the book for more information: "] pub type MyObject = super::MyObjectQt; } } diff --git a/crates/cxx-qt-gen/test_outputs/invokables.rs b/crates/cxx-qt-gen/test_outputs/invokables.rs index 4d30329a4..55844f6e4 100644 --- a/crates/cxx-qt-gen/test_outputs/invokables.rs +++ b/crates/cxx-qt-gen/test_outputs/invokables.rs @@ -20,6 +20,12 @@ mod ffi { } unsafe extern "C++" { + #[doc = "The C++ type for the QObject "] + #[doc = "MyObject"] + #[doc = "\n"] + #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "\n"] + #[doc = "See the book for more information: "] #[cxx_name = "MyObject"] type MyObjectQt; } @@ -82,11 +88,21 @@ mod ffi { } unsafe extern "C++" { + #[doc = r" Specialised version of CxxQtThread, which can be moved into other threads."] + #[doc = r""] + #[doc = r" CXX doesn't support having generic types in the function yet"] + #[doc = r" so we cannot have CxxQtThread in cxx-qt-lib and then use that here"] + #[doc = r" For now we use a type alias in C++ then use it like a normal type here"] + #[doc = r" https://github.com/dtolnay/cxx/issues/683"] type MyObjectCxxQtThread; + #[doc = r" Retrieve an immutable reference to the Rust struct backing this C++ object"] #[cxx_name = "unsafeRust"] fn rust(self: &MyObjectQt) -> &MyObject; + #[doc = r" Create an instance of a CxxQtThread"] + #[doc = r""] + #[doc = r" This allows for queueing closures onto the Qt event loop from a background thread."] #[cxx_name = "qtThread"] fn qt_thread(self: &MyObjectQt) -> UniquePtr; @@ -97,12 +113,18 @@ mod ffi { arg: Box, ) -> Result<()>; + #[doc = "Generated CXX-Qt method which creates a new"] + #[doc = "MyObjectQt"] + #[doc = "as a UniquePtr with no parent in Qt"] #[rust_name = "new_cpp_object_my_object_qt"] #[namespace = "cxx_qt::my_object::cxx_qt_my_object"] fn newCppObject() -> UniquePtr; } extern "C++" { + #[doc = r" Retrieve a mutable reference to the Rust struct backing this C++ object"] + #[doc = r""] + #[doc = r" This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually."] #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut MyObjectQt>) -> Pin<&mut MyObject>; } @@ -134,6 +156,8 @@ mod cxx_qt_ffi { pub struct MyObject; impl MyObject { + #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] + #[doc = "invokable"] pub fn invokable_wrapper(self: &MyObject, cpp: &MyObjectQt) { cpp.invokable(); } @@ -146,6 +170,8 @@ mod cxx_qt_ffi { } impl MyObject { + #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] + #[doc = "invokable_mutable"] pub fn invokable_mutable_wrapper(self: &mut MyObject, cpp: Pin<&mut MyObjectQt>) { cpp.invokable_mutable(); } @@ -158,6 +184,8 @@ mod cxx_qt_ffi { } impl MyObject { + #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] + #[doc = "invokable_parameters"] pub fn invokable_parameters_wrapper( self: &MyObject, cpp: &MyObjectQt, @@ -181,6 +209,8 @@ mod cxx_qt_ffi { } impl MyObject { + #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] + #[doc = "invokable_return_opaque"] pub fn invokable_return_opaque_wrapper( self: &mut MyObject, cpp: Pin<&mut MyObjectQt>, @@ -196,6 +226,8 @@ mod cxx_qt_ffi { } impl MyObject { + #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] + #[doc = "invokable_return_trivial"] pub fn invokable_return_trivial_wrapper( self: &mut MyObject, cpp: Pin<&mut MyObjectQt>, @@ -211,6 +243,8 @@ mod cxx_qt_ffi { } impl MyObject { + #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] + #[doc = "invokable_final"] pub fn invokable_final_wrapper(self: &MyObject, cpp: &MyObjectQt) { cpp.invokable_final(); } @@ -223,6 +257,8 @@ mod cxx_qt_ffi { } impl MyObject { + #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] + #[doc = "invokable_override"] pub fn invokable_override_wrapper(self: &MyObject, cpp: &MyObjectQt) { cpp.invokable_override(); } @@ -235,6 +271,8 @@ mod cxx_qt_ffi { } impl MyObject { + #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] + #[doc = "invokable_virtual"] pub fn invokable_virtual_wrapper(self: &MyObject, cpp: &MyObjectQt) { cpp.invokable_virtual(); } @@ -267,6 +305,7 @@ mod cxx_qt_ffi { unsafe impl Send for MyObjectCxxQtThread {} impl MyObjectCxxQtThread { + #[doc = r" Queue the given closure onto the Qt event loop for this QObject"] pub fn queue(&self, f: F) -> std::result::Result<(), cxx::Exception> where F: FnOnce(std::pin::Pin<&mut MyObjectQt>), @@ -286,15 +325,24 @@ mod cxx_qt_ffi { } } + #[doc = r" Generated CXX-Qt thread helper for a QObject"] pub struct MyObjectCxxQtThreadQueuedFn { inner: std::boxed::Box) + Send>, } + #[doc = r" Generated CXX-Qt method which creates a boxed rust struct of a QObject"] pub fn create_rs_my_object() -> std::boxed::Box { std::default::Default::default() } + #[doc = r" Generated CXX-Qt module containing type alias to the C++ type of the QObjects"] pub mod qobject { + #[doc = "The C++ type for the QObject "] + #[doc = "MyObject"] + #[doc = "\n"] + #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "\n"] + #[doc = "See the book for more information: "] pub type MyObject = super::MyObjectQt; } } diff --git a/crates/cxx-qt-gen/test_outputs/passthrough_and_naming.rs b/crates/cxx-qt-gen/test_outputs/passthrough_and_naming.rs index b54847b77..2af5ac130 100644 --- a/crates/cxx-qt-gen/test_outputs/passthrough_and_naming.rs +++ b/crates/cxx-qt-gen/test_outputs/passthrough_and_naming.rs @@ -75,6 +75,12 @@ pub mod ffi { } unsafe extern "C++" { + #[doc = "The C++ type for the QObject "] + #[doc = "MyObject"] + #[doc = "\n"] + #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "\n"] + #[doc = "See the book for more information: "] #[cxx_name = "MyObject"] type MyObjectQt; } @@ -95,6 +101,12 @@ pub mod ffi { } unsafe extern "C++" { + #[doc = "Notify signal for the Q_PROPERTY"] + #[doc = "property_name"] + #[doc = "\n"] + #[doc = "This can be used to manually notify a change when the unsafe mutable getter,"] + #[doc = "property_name_mut"] + #[doc = ", is used."] #[rust_name = "property_name_changed"] fn propertyNameChanged(self: Pin<&mut MyObjectQt>); } @@ -110,11 +122,21 @@ pub mod ffi { } unsafe extern "C++" { + #[doc = r" Specialised version of CxxQtThread, which can be moved into other threads."] + #[doc = r""] + #[doc = r" CXX doesn't support having generic types in the function yet"] + #[doc = r" so we cannot have CxxQtThread in cxx-qt-lib and then use that here"] + #[doc = r" For now we use a type alias in C++ then use it like a normal type here"] + #[doc = r" https://github.com/dtolnay/cxx/issues/683"] type MyObjectCxxQtThread; + #[doc = r" Retrieve an immutable reference to the Rust struct backing this C++ object"] #[cxx_name = "unsafeRust"] fn rust(self: &MyObjectQt) -> &MyObject; + #[doc = r" Create an instance of a CxxQtThread"] + #[doc = r""] + #[doc = r" This allows for queueing closures onto the Qt event loop from a background thread."] #[cxx_name = "qtThread"] fn qt_thread(self: &MyObjectQt) -> UniquePtr; @@ -125,12 +147,18 @@ pub mod ffi { arg: Box, ) -> Result<()>; + #[doc = "Generated CXX-Qt method which creates a new"] + #[doc = "MyObjectQt"] + #[doc = "as a UniquePtr with no parent in Qt"] #[rust_name = "new_cpp_object_my_object_qt"] #[namespace = "cxx_qt::multi_object::cxx_qt_my_object"] fn newCppObject() -> UniquePtr; } extern "C++" { + #[doc = r" Retrieve a mutable reference to the Rust struct backing this C++ object"] + #[doc = r""] + #[doc = r" This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually."] #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut MyObjectQt>) -> Pin<&mut MyObject>; } @@ -145,6 +173,12 @@ pub mod ffi { } unsafe extern "C++" { + #[doc = "The C++ type for the QObject "] + #[doc = "SecondObject"] + #[doc = "\n"] + #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "\n"] + #[doc = "See the book for more information: "] #[cxx_name = "SecondObject"] type SecondObjectQt; } @@ -165,6 +199,12 @@ pub mod ffi { } unsafe extern "C++" { + #[doc = "Notify signal for the Q_PROPERTY"] + #[doc = "property_name"] + #[doc = "\n"] + #[doc = "This can be used to manually notify a change when the unsafe mutable getter,"] + #[doc = "property_name_mut"] + #[doc = ", is used."] #[rust_name = "property_name_changed"] fn propertyNameChanged(self: Pin<&mut SecondObjectQt>); } @@ -180,9 +220,19 @@ pub mod ffi { } unsafe extern "C++" { + #[doc = r" Specialised version of CxxQtThread, which can be moved into other threads."] + #[doc = r""] + #[doc = r" CXX doesn't support having generic types in the function yet"] + #[doc = r" so we cannot have CxxQtThread in cxx-qt-lib and then use that here"] + #[doc = r" For now we use a type alias in C++ then use it like a normal type here"] + #[doc = r" https://github.com/dtolnay/cxx/issues/683"] type SecondObjectCxxQtThread; + #[doc = r" Retrieve an immutable reference to the Rust struct backing this C++ object"] #[cxx_name = "unsafeRust"] fn rust(self: &SecondObjectQt) -> &SecondObject; + #[doc = r" Create an instance of a CxxQtThread"] + #[doc = r""] + #[doc = r" This allows for queueing closures onto the Qt event loop from a background thread."] #[cxx_name = "qtThread"] fn qt_thread(self: &SecondObjectQt) -> UniquePtr; #[cxx_name = "queue"] @@ -191,12 +241,18 @@ pub mod ffi { func: fn(Pin<&mut SecondObjectQt>, Box), arg: Box, ) -> Result<()>; + #[doc = "Generated CXX-Qt method which creates a new"] + #[doc = "SecondObjectQt"] + #[doc = "as a UniquePtr with no parent in Qt"] #[rust_name = "new_cpp_object_second_object_qt"] #[namespace = "cxx_qt::multi_object::cxx_qt_second_object"] fn newCppObject() -> UniquePtr; } extern "C++" { + #[doc = r" Retrieve a mutable reference to the Rust struct backing this C++ object"] + #[doc = r""] + #[doc = r" This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually."] #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut SecondObjectQt>) -> Pin<&mut SecondObject>; } @@ -246,30 +302,49 @@ mod cxx_qt_ffi { } impl MyObject { + #[doc = "Getter for the Q_PROPERTY "] + #[doc = "property_name"] + #[doc = "\n"] + #[doc = "This is an internal method used by C++ to retrieve the value of the Q_PROPERTY in the Rust struct"] pub fn property_name<'a>(&'a self, cpp: &'a MyObjectQt) -> &'a i32 { cpp.property_name() } } impl MyObjectQt { + #[doc = "Getter for the Q_PROPERTY "] + #[doc = "property_name"] pub fn property_name(&self) -> &i32 { &self.rust().property_name } } impl MyObjectQt { + #[doc = "unsafe getter for the Q_PROPERTY "] + #[doc = "property_name"] + #[doc = "\n"] + #[doc = "This allows for modifying the Q_PROPERTY without calling the property changed Q_SIGNAL"] + #[doc = "\n"] + #[doc = "After modifying the property, make sure to call the corresponding changed signal: "] + #[doc = "property_name_changed"] pub unsafe fn property_name_mut<'a>(mut self: Pin<&'a mut Self>) -> &'a mut i32 { &mut self.rust_mut().get_unchecked_mut().property_name } } impl MyObject { + #[doc = "Setter for the Q_PROPERTY "] + #[doc = "property_name"] + #[doc = "\n"] + #[doc = "This is an internal method used by C++ to set the value of the Q_PROPERTY in the Rust struct"] pub fn set_property_name(&mut self, cpp: Pin<&mut MyObjectQt>, value: i32) { cpp.set_property_name(value); } } impl MyObjectQt { + #[doc = "Setter for the Q_PROPERTY "] + #[doc = "property_name"] pub fn set_property_name(mut self: Pin<&mut Self>, value: i32) { if self.rust().property_name == value { return; @@ -282,6 +357,8 @@ mod cxx_qt_ffi { } impl MyObject { + #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] + #[doc = "invokable_name"] pub fn invokable_name_wrapper(self: &mut MyObject, cpp: Pin<&mut MyObjectQt>) { cpp.invokable_name(); } @@ -311,6 +388,10 @@ mod cxx_qt_ffi { } impl MyObjectQt { + #[doc = "Emit the signal from the enum "] + #[doc = "MySignals"] + #[doc = " on the QObject "] + #[doc = "MyObject"] pub fn emit(self: Pin<&mut Self>, signal: MySignals) { match signal { MySignals::Ready {} => self.emit_ready(), @@ -321,6 +402,7 @@ mod cxx_qt_ffi { unsafe impl Send for MyObjectCxxQtThread {} impl MyObjectCxxQtThread { + #[doc = r" Queue the given closure onto the Qt event loop for this QObject"] pub fn queue(&self, f: F) -> std::result::Result<(), cxx::Exception> where F: FnOnce(std::pin::Pin<&mut MyObjectQt>), @@ -340,10 +422,12 @@ mod cxx_qt_ffi { } } + #[doc = r" Generated CXX-Qt thread helper for a QObject"] pub struct MyObjectCxxQtThreadQueuedFn { inner: std::boxed::Box) + Send>, } + #[doc = r" Generated CXX-Qt method which creates a boxed rust struct of a QObject"] pub fn create_rs_my_object() -> std::boxed::Box { std::default::Default::default() } @@ -359,29 +443,48 @@ mod cxx_qt_ffi { } impl SecondObject { + #[doc = "Getter for the Q_PROPERTY "] + #[doc = "property_name"] + #[doc = "\n"] + #[doc = "This is an internal method used by C++ to retrieve the value of the Q_PROPERTY in the Rust struct"] pub fn property_name<'a>(&'a self, cpp: &'a SecondObjectQt) -> &'a i32 { cpp.property_name() } } impl SecondObjectQt { + #[doc = "Getter for the Q_PROPERTY "] + #[doc = "property_name"] pub fn property_name(&self) -> &i32 { &self.rust().property_name } } impl SecondObjectQt { + #[doc = "unsafe getter for the Q_PROPERTY "] + #[doc = "property_name"] + #[doc = "\n"] + #[doc = "This allows for modifying the Q_PROPERTY without calling the property changed Q_SIGNAL"] + #[doc = "\n"] + #[doc = "After modifying the property, make sure to call the corresponding changed signal: "] + #[doc = "property_name_changed"] pub unsafe fn property_name_mut<'a>(mut self: Pin<&'a mut Self>) -> &'a mut i32 { &mut self.rust_mut().get_unchecked_mut().property_name } } impl SecondObject { + #[doc = "Setter for the Q_PROPERTY "] + #[doc = "property_name"] + #[doc = "\n"] + #[doc = "This is an internal method used by C++ to set the value of the Q_PROPERTY in the Rust struct"] pub fn set_property_name(&mut self, cpp: Pin<&mut SecondObjectQt>, value: i32) { cpp.set_property_name(value); } } impl SecondObjectQt { + #[doc = "Setter for the Q_PROPERTY "] + #[doc = "property_name"] pub fn set_property_name(mut self: Pin<&mut Self>, value: i32) { if self.rust().property_name == value { return; @@ -394,6 +497,8 @@ mod cxx_qt_ffi { } impl SecondObject { + #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] + #[doc = "invokable_name"] pub fn invokable_name_wrapper(self: &mut SecondObject, cpp: Pin<&mut SecondObjectQt>) { cpp.invokable_name(); } @@ -411,6 +516,10 @@ mod cxx_qt_ffi { } impl SecondObjectQt { + #[doc = "Emit the signal from the enum "] + #[doc = "SecondSignals"] + #[doc = " on the QObject "] + #[doc = "SecondObject"] pub fn emit(self: Pin<&mut Self>, signal: SecondSignals) { match signal { SecondSignals::Ready {} => self.emit_ready(), @@ -421,6 +530,7 @@ mod cxx_qt_ffi { unsafe impl Send for SecondObjectCxxQtThread {} impl SecondObjectCxxQtThread { + #[doc = r" Queue the given closure onto the Qt event loop for this QObject"] pub fn queue(&self, f: F) -> std::result::Result<(), cxx::Exception> where F: FnOnce(std::pin::Pin<&mut SecondObjectQt>), @@ -440,16 +550,31 @@ mod cxx_qt_ffi { } } + #[doc = r" Generated CXX-Qt thread helper for a QObject"] pub struct SecondObjectCxxQtThreadQueuedFn { inner: std::boxed::Box) + Send>, } + #[doc = r" Generated CXX-Qt method which creates a boxed rust struct of a QObject"] pub fn create_rs_second_object() -> std::boxed::Box { std::default::Default::default() } + #[doc = r" Generated CXX-Qt module containing type alias to the C++ type of the QObjects"] pub mod qobject { + #[doc = "The C++ type for the QObject "] + #[doc = "MyObject"] + #[doc = "\n"] + #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "\n"] + #[doc = "See the book for more information: "] pub type MyObject = super::MyObjectQt; + #[doc = "The C++ type for the QObject "] + #[doc = "SecondObject"] + #[doc = "\n"] + #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "\n"] + #[doc = "See the book for more information: "] pub type SecondObject = super::SecondObjectQt; } } diff --git a/crates/cxx-qt-gen/test_outputs/properties.rs b/crates/cxx-qt-gen/test_outputs/properties.rs index d96994621..5d999c47d 100644 --- a/crates/cxx-qt-gen/test_outputs/properties.rs +++ b/crates/cxx-qt-gen/test_outputs/properties.rs @@ -18,6 +18,12 @@ mod ffi { } unsafe extern "C++" { + #[doc = "The C++ type for the QObject "] + #[doc = "MyObject"] + #[doc = "\n"] + #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "\n"] + #[doc = "See the book for more information: "] #[cxx_name = "MyObject"] type MyObjectQt; } @@ -38,6 +44,12 @@ mod ffi { } unsafe extern "C++" { + #[doc = "Notify signal for the Q_PROPERTY"] + #[doc = "primitive"] + #[doc = "\n"] + #[doc = "This can be used to manually notify a change when the unsafe mutable getter,"] + #[doc = "primitive_mut"] + #[doc = ", is used."] #[rust_name = "primitive_changed"] fn primitiveChanged(self: Pin<&mut MyObjectQt>); } @@ -53,6 +65,12 @@ mod ffi { } unsafe extern "C++" { + #[doc = "Notify signal for the Q_PROPERTY"] + #[doc = "trivial"] + #[doc = "\n"] + #[doc = "This can be used to manually notify a change when the unsafe mutable getter,"] + #[doc = "trivial_mut"] + #[doc = ", is used."] #[rust_name = "trivial_changed"] fn trivialChanged(self: Pin<&mut MyObjectQt>); } @@ -68,16 +86,32 @@ mod ffi { } unsafe extern "C++" { + #[doc = "Notify signal for the Q_PROPERTY"] + #[doc = "opaque"] + #[doc = "\n"] + #[doc = "This can be used to manually notify a change when the unsafe mutable getter,"] + #[doc = "opaque_mut"] + #[doc = ", is used."] #[rust_name = "opaque_changed"] fn opaqueChanged(self: Pin<&mut MyObjectQt>); } unsafe extern "C++" { + #[doc = r" Specialised version of CxxQtThread, which can be moved into other threads."] + #[doc = r""] + #[doc = r" CXX doesn't support having generic types in the function yet"] + #[doc = r" so we cannot have CxxQtThread in cxx-qt-lib and then use that here"] + #[doc = r" For now we use a type alias in C++ then use it like a normal type here"] + #[doc = r" https://github.com/dtolnay/cxx/issues/683"] type MyObjectCxxQtThread; + #[doc = r" Retrieve an immutable reference to the Rust struct backing this C++ object"] #[cxx_name = "unsafeRust"] fn rust(self: &MyObjectQt) -> &MyObject; + #[doc = r" Create an instance of a CxxQtThread"] + #[doc = r""] + #[doc = r" This allows for queueing closures onto the Qt event loop from a background thread."] #[cxx_name = "qtThread"] fn qt_thread(self: &MyObjectQt) -> UniquePtr; @@ -88,12 +122,18 @@ mod ffi { arg: Box, ) -> Result<()>; + #[doc = "Generated CXX-Qt method which creates a new"] + #[doc = "MyObjectQt"] + #[doc = "as a UniquePtr with no parent in Qt"] #[rust_name = "new_cpp_object_my_object_qt"] #[namespace = "cxx_qt::my_object::cxx_qt_my_object"] fn newCppObject() -> UniquePtr; } extern "C++" { + #[doc = r" Retrieve a mutable reference to the Rust struct backing this C++ object"] + #[doc = r""] + #[doc = r" This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually."] #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut MyObjectQt>) -> Pin<&mut MyObject>; } @@ -125,30 +165,49 @@ mod cxx_qt_ffi { } impl MyObject { + #[doc = "Getter for the Q_PROPERTY "] + #[doc = "primitive"] + #[doc = "\n"] + #[doc = "This is an internal method used by C++ to retrieve the value of the Q_PROPERTY in the Rust struct"] pub fn primitive<'a>(&'a self, cpp: &'a MyObjectQt) -> &'a i32 { cpp.primitive() } } impl MyObjectQt { + #[doc = "Getter for the Q_PROPERTY "] + #[doc = "primitive"] pub fn primitive(&self) -> &i32 { &self.rust().primitive } } impl MyObjectQt { + #[doc = "unsafe getter for the Q_PROPERTY "] + #[doc = "primitive"] + #[doc = "\n"] + #[doc = "This allows for modifying the Q_PROPERTY without calling the property changed Q_SIGNAL"] + #[doc = "\n"] + #[doc = "After modifying the property, make sure to call the corresponding changed signal: "] + #[doc = "primitive_changed"] pub unsafe fn primitive_mut<'a>(mut self: Pin<&'a mut Self>) -> &'a mut i32 { &mut self.rust_mut().get_unchecked_mut().primitive } } impl MyObject { + #[doc = "Setter for the Q_PROPERTY "] + #[doc = "primitive"] + #[doc = "\n"] + #[doc = "This is an internal method used by C++ to set the value of the Q_PROPERTY in the Rust struct"] pub fn set_primitive(&mut self, cpp: Pin<&mut MyObjectQt>, value: i32) { cpp.set_primitive(value); } } impl MyObjectQt { + #[doc = "Setter for the Q_PROPERTY "] + #[doc = "primitive"] pub fn set_primitive(mut self: Pin<&mut Self>, value: i32) { if self.rust().primitive == value { return; @@ -161,30 +220,49 @@ mod cxx_qt_ffi { } impl MyObject { + #[doc = "Getter for the Q_PROPERTY "] + #[doc = "trivial"] + #[doc = "\n"] + #[doc = "This is an internal method used by C++ to retrieve the value of the Q_PROPERTY in the Rust struct"] pub fn trivial<'a>(&'a self, cpp: &'a MyObjectQt) -> &'a QPoint { cpp.trivial() } } impl MyObjectQt { + #[doc = "Getter for the Q_PROPERTY "] + #[doc = "trivial"] pub fn trivial(&self) -> &QPoint { &self.rust().trivial } } impl MyObjectQt { + #[doc = "unsafe getter for the Q_PROPERTY "] + #[doc = "trivial"] + #[doc = "\n"] + #[doc = "This allows for modifying the Q_PROPERTY without calling the property changed Q_SIGNAL"] + #[doc = "\n"] + #[doc = "After modifying the property, make sure to call the corresponding changed signal: "] + #[doc = "trivial_changed"] pub unsafe fn trivial_mut<'a>(mut self: Pin<&'a mut Self>) -> &'a mut QPoint { &mut self.rust_mut().get_unchecked_mut().trivial } } impl MyObject { + #[doc = "Setter for the Q_PROPERTY "] + #[doc = "trivial"] + #[doc = "\n"] + #[doc = "This is an internal method used by C++ to set the value of the Q_PROPERTY in the Rust struct"] pub fn set_trivial(&mut self, cpp: Pin<&mut MyObjectQt>, value: QPoint) { cpp.set_trivial(value); } } impl MyObjectQt { + #[doc = "Setter for the Q_PROPERTY "] + #[doc = "trivial"] pub fn set_trivial(mut self: Pin<&mut Self>, value: QPoint) { if self.rust().trivial == value { return; @@ -197,30 +275,49 @@ mod cxx_qt_ffi { } impl MyObject { + #[doc = "Getter for the Q_PROPERTY "] + #[doc = "opaque"] + #[doc = "\n"] + #[doc = "This is an internal method used by C++ to retrieve the value of the Q_PROPERTY in the Rust struct"] pub fn opaque<'a>(&'a self, cpp: &'a MyObjectQt) -> &'a UniquePtr { cpp.opaque() } } impl MyObjectQt { + #[doc = "Getter for the Q_PROPERTY "] + #[doc = "opaque"] pub fn opaque(&self) -> &UniquePtr { &self.rust().opaque } } impl MyObjectQt { + #[doc = "unsafe getter for the Q_PROPERTY "] + #[doc = "opaque"] + #[doc = "\n"] + #[doc = "This allows for modifying the Q_PROPERTY without calling the property changed Q_SIGNAL"] + #[doc = "\n"] + #[doc = "After modifying the property, make sure to call the corresponding changed signal: "] + #[doc = "opaque_changed"] pub unsafe fn opaque_mut<'a>(mut self: Pin<&'a mut Self>) -> &'a mut UniquePtr { &mut self.rust_mut().get_unchecked_mut().opaque } } impl MyObject { + #[doc = "Setter for the Q_PROPERTY "] + #[doc = "opaque"] + #[doc = "\n"] + #[doc = "This is an internal method used by C++ to set the value of the Q_PROPERTY in the Rust struct"] pub fn set_opaque(&mut self, cpp: Pin<&mut MyObjectQt>, value: UniquePtr) { cpp.set_opaque(value); } } impl MyObjectQt { + #[doc = "Setter for the Q_PROPERTY "] + #[doc = "opaque"] pub fn set_opaque(mut self: Pin<&mut Self>, value: UniquePtr) { if self.rust().opaque == value { return; @@ -275,6 +372,7 @@ mod cxx_qt_ffi { unsafe impl Send for MyObjectCxxQtThread {} impl MyObjectCxxQtThread { + #[doc = r" Queue the given closure onto the Qt event loop for this QObject"] pub fn queue(&self, f: F) -> std::result::Result<(), cxx::Exception> where F: FnOnce(std::pin::Pin<&mut MyObjectQt>), @@ -294,15 +392,24 @@ mod cxx_qt_ffi { } } + #[doc = r" Generated CXX-Qt thread helper for a QObject"] pub struct MyObjectCxxQtThreadQueuedFn { inner: std::boxed::Box) + Send>, } + #[doc = r" Generated CXX-Qt method which creates a boxed rust struct of a QObject"] pub fn create_rs_my_object() -> std::boxed::Box { std::default::Default::default() } + #[doc = r" Generated CXX-Qt module containing type alias to the C++ type of the QObjects"] pub mod qobject { + #[doc = "The C++ type for the QObject "] + #[doc = "MyObject"] + #[doc = "\n"] + #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "\n"] + #[doc = "See the book for more information: "] pub type MyObject = super::MyObjectQt; } } diff --git a/crates/cxx-qt-gen/test_outputs/signals.rs b/crates/cxx-qt-gen/test_outputs/signals.rs index e36954636..751a887dd 100644 --- a/crates/cxx-qt-gen/test_outputs/signals.rs +++ b/crates/cxx-qt-gen/test_outputs/signals.rs @@ -18,6 +18,12 @@ mod ffi { } unsafe extern "C++" { + #[doc = "The C++ type for the QObject "] + #[doc = "MyObject"] + #[doc = "\n"] + #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "\n"] + #[doc = "See the book for more information: "] #[cxx_name = "MyObject"] type MyObjectQt; } @@ -60,11 +66,21 @@ mod ffi { } unsafe extern "C++" { + #[doc = r" Specialised version of CxxQtThread, which can be moved into other threads."] + #[doc = r""] + #[doc = r" CXX doesn't support having generic types in the function yet"] + #[doc = r" so we cannot have CxxQtThread in cxx-qt-lib and then use that here"] + #[doc = r" For now we use a type alias in C++ then use it like a normal type here"] + #[doc = r" https://github.com/dtolnay/cxx/issues/683"] type MyObjectCxxQtThread; + #[doc = r" Retrieve an immutable reference to the Rust struct backing this C++ object"] #[cxx_name = "unsafeRust"] fn rust(self: &MyObjectQt) -> &MyObject; + #[doc = r" Create an instance of a CxxQtThread"] + #[doc = r""] + #[doc = r" This allows for queueing closures onto the Qt event loop from a background thread."] #[cxx_name = "qtThread"] fn qt_thread(self: &MyObjectQt) -> UniquePtr; @@ -75,12 +91,18 @@ mod ffi { arg: Box, ) -> Result<()>; + #[doc = "Generated CXX-Qt method which creates a new"] + #[doc = "MyObjectQt"] + #[doc = "as a UniquePtr with no parent in Qt"] #[rust_name = "new_cpp_object_my_object_qt"] #[namespace = "cxx_qt::my_object::cxx_qt_my_object"] fn newCppObject() -> UniquePtr; } extern "C++" { + #[doc = r" Retrieve a mutable reference to the Rust struct backing this C++ object"] + #[doc = r""] + #[doc = r" This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually."] #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut MyObjectQt>) -> Pin<&mut MyObject>; } @@ -106,6 +128,8 @@ mod cxx_qt_ffi { pub struct MyObject; impl MyObject { + #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] + #[doc = "invokable"] pub fn invokable_wrapper(self: &mut MyObject, cpp: Pin<&mut MyObjectQt>) { cpp.invokable(); } @@ -139,6 +163,10 @@ mod cxx_qt_ffi { } impl MyObjectQt { + #[doc = "Emit the signal from the enum "] + #[doc = "MySignals"] + #[doc = " on the QObject "] + #[doc = "MyObject"] pub fn emit(self: Pin<&mut Self>, signal: MySignals) { match signal { MySignals::Ready {} => self.emit_ready(), @@ -161,6 +189,7 @@ mod cxx_qt_ffi { unsafe impl Send for MyObjectCxxQtThread {} impl MyObjectCxxQtThread { + #[doc = r" Queue the given closure onto the Qt event loop for this QObject"] pub fn queue(&self, f: F) -> std::result::Result<(), cxx::Exception> where F: FnOnce(std::pin::Pin<&mut MyObjectQt>), @@ -180,15 +209,24 @@ mod cxx_qt_ffi { } } + #[doc = r" Generated CXX-Qt thread helper for a QObject"] pub struct MyObjectCxxQtThreadQueuedFn { inner: std::boxed::Box) + Send>, } + #[doc = r" Generated CXX-Qt method which creates a boxed rust struct of a QObject"] pub fn create_rs_my_object() -> std::boxed::Box { std::default::Default::default() } + #[doc = r" Generated CXX-Qt module containing type alias to the C++ type of the QObjects"] pub mod qobject { + #[doc = "The C++ type for the QObject "] + #[doc = "MyObject"] + #[doc = "\n"] + #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "\n"] + #[doc = "See the book for more information: "] pub type MyObject = super::MyObjectQt; } } From 5219df3d368d38b7693b558c8339a239ea09482e Mon Sep 17 00:00:00 2001 From: Andrew Hayzen Date: Mon, 8 May 2023 12:40:40 +0100 Subject: [PATCH 2/7] docs: hide internal methods from documentation Related to #529 --- .../cxx-qt-gen/src/generator/rust/inherit.rs | 21 +++++++++-- .../src/generator/rust/invokable.rs | 16 +++----- .../src/generator/rust/property/getter.rs | 5 +-- .../src/generator/rust/property/mod.rs | 30 +++------------ .../src/generator/rust/property/setter.rs | 5 +-- .../cxx-qt-gen/src/generator/rust/signals.rs | 5 +++ crates/cxx-qt-gen/src/writer/rust/mod.rs | 19 ++++++++-- crates/cxx-qt-gen/test_outputs/inheritance.rs | 17 ++++++--- crates/cxx-qt-gen/test_outputs/invokables.rs | 29 ++++++--------- .../test_outputs/passthrough_and_naming.rs | 37 ++++++++----------- crates/cxx-qt-gen/test_outputs/properties.rs | 35 +++++------------- crates/cxx-qt-gen/test_outputs/signals.rs | 11 ++++-- 12 files changed, 107 insertions(+), 123 deletions(-) diff --git a/crates/cxx-qt-gen/src/generator/rust/inherit.rs b/crates/cxx-qt-gen/src/generator/rust/inherit.rs index 523f3f74e..ef1d7ae1c 100644 --- a/crates/cxx-qt-gen/src/generator/rust/inherit.rs +++ b/crates/cxx-qt-gen/src/generator/rust/inherit.rs @@ -32,6 +32,7 @@ pub fn generate( .collect::>(); let ident = &method.method.sig.ident; let cxx_name_string = &method.wrapper_ident().to_string(); + let ident_cpp_str = method.ident.cpp.to_string(); let self_param = if method.mutable { quote! { self: Pin<&mut #qobject_name> } } else { @@ -46,7 +47,10 @@ pub fn generate( } syn::parse2(quote! { #unsafe_block extern "C++" { - #[cxx_name=#cxx_name_string] + #[doc = "CXX-Qt generated method which calls the C++ method"] + #[doc = #ident_cpp_str] + #[doc = "on the base class"] + #[cxx_name = #cxx_name_string] #unsafe_call fn #ident(#self_param, #(#parameters),*) #return_type; } }) @@ -91,7 +95,10 @@ mod tests { &generated.cxx_mod_contents[0], quote! { unsafe extern "C++" { - #[cxx_name="testCxxQtInherit"] + #[doc = "CXX-Qt generated method which calls the C++ method"] + #[doc = "test"] + #[doc = "on the base class"] + #[cxx_name = "testCxxQtInherit"] fn test(self: Pin<&mut MyObjectQt>, a: B, b: C); } }, @@ -115,7 +122,10 @@ mod tests { &generated.cxx_mod_contents[0], quote! { unsafe extern "C++" { - #[cxx_name="testCxxQtInherit"] + #[doc = "CXX-Qt generated method which calls the C++ method"] + #[doc = "test"] + #[doc = "on the base class"] + #[cxx_name = "testCxxQtInherit"] fn test(self: &MyObjectQt, a: B, b: C); } }, @@ -140,7 +150,10 @@ mod tests { // TODO: Maybe remove the trailing comma after self? quote! { extern "C++" { - #[cxx_name="testCxxQtInherit"] + #[doc = "CXX-Qt generated method which calls the C++ method"] + #[doc = "test"] + #[doc = "on the base class"] + #[cxx_name = "testCxxQtInherit"] unsafe fn test(self: &MyObjectQt,); } }, diff --git a/crates/cxx-qt-gen/src/generator/rust/invokable.rs b/crates/cxx-qt-gen/src/generator/rust/invokable.rs index 466a42fad..a4aa8cd9f 100644 --- a/crates/cxx-qt-gen/src/generator/rust/invokable.rs +++ b/crates/cxx-qt-gen/src/generator/rust/invokable.rs @@ -30,7 +30,6 @@ pub fn generate_rust_invokables( let wrapper_ident_cpp = idents.wrapper.cpp.to_string(); let wrapper_ident_rust = &idents.wrapper.rust; let invokable_ident_rust = &idents.name.rust; - let invokable_ident_rust_str = invokable_ident_rust.to_string(); let original_method = &invokable.method; let cpp_struct = if invokable.mutable { @@ -95,8 +94,7 @@ pub fn generate_rust_invokables( // TODO: not all methods have a wrapper quote! { impl #rust_struct_name_rust { - #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] - #[doc = #invokable_ident_rust_str] + #[doc(hidden)] pub #has_unsafe fn #wrapper_ident_rust(#parameter_signatures) #return_type { #has_return cpp.#invokable_ident_rust(#(#parameter_names),*); } @@ -197,8 +195,7 @@ mod tests { &generated.cxx_qt_mod_contents[0], quote! { impl MyObject { - #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] - #[doc = "void_invokable"] + #[doc(hidden)] pub fn void_invokable_wrapper(self: &MyObject, cpp: &MyObjectQt) { cpp.void_invokable(); } @@ -228,8 +225,7 @@ mod tests { &generated.cxx_qt_mod_contents[2], quote! { impl MyObject { - #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] - #[doc = "trivial_invokable"] + #[doc(hidden)] pub fn trivial_invokable_wrapper(self: &MyObject, cpp: &MyObjectQt, param: i32) -> i32 { return cpp.trivial_invokable(param); } @@ -259,8 +255,7 @@ mod tests { &generated.cxx_qt_mod_contents[4], quote! { impl MyObject { - #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] - #[doc = "opaque_invokable"] + #[doc(hidden)] pub fn opaque_invokable_wrapper(self: &mut MyObject, cpp: Pin<&mut MyObjectQt>, param: &QColor) -> UniquePtr { return cpp.opaque_invokable(param); } @@ -290,8 +285,7 @@ mod tests { &generated.cxx_qt_mod_contents[6], quote! { impl MyObject { - #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] - #[doc = "unsafe_invokable"] + #[doc(hidden)] pub unsafe fn unsafe_invokable_wrapper(self: &MyObject, cpp: &MyObjectQt, param: *mut T) -> *mut T { return cpp.unsafe_invokable(param); } diff --git a/crates/cxx-qt-gen/src/generator/rust/property/getter.rs b/crates/cxx-qt-gen/src/generator/rust/property/getter.rs index b70a272bb..ad262a653 100644 --- a/crates/cxx-qt-gen/src/generator/rust/property/getter.rs +++ b/crates/cxx-qt-gen/src/generator/rust/property/getter.rs @@ -34,10 +34,7 @@ pub fn generate( implementation: vec![ quote! { impl #rust_struct_name_rust { - #[doc = "Getter for the Q_PROPERTY "] - #[doc = #ident_str] - #[doc = "\n"] - #[doc = "This is an internal method used by C++ to retrieve the value of the Q_PROPERTY in the Rust struct"] + #[doc(hidden)] pub fn #getter_rust<'a>(&'a self, cpp: &'a #cpp_class_name_rust) -> &'a #ty { cpp.#getter_rust() } diff --git a/crates/cxx-qt-gen/src/generator/rust/property/mod.rs b/crates/cxx-qt-gen/src/generator/rust/property/mod.rs index 52a61bb1c..a2a6a5935 100644 --- a/crates/cxx-qt-gen/src/generator/rust/property/mod.rs +++ b/crates/cxx-qt-gen/src/generator/rust/property/mod.rs @@ -110,10 +110,7 @@ mod tests { generated.cxx_qt_mod_contents[0], parse_quote! { impl MyObject { - #[doc = "Getter for the Q_PROPERTY "] - #[doc = "trivial_property"] - #[doc = "\n"] - #[doc = "This is an internal method used by C++ to retrieve the value of the Q_PROPERTY in the Rust struct"] + #[doc(hidden)] pub fn trivial_property<'a>(&'a self, cpp: &'a MyObjectQt) -> &'a i32 { cpp.trivial_property() } @@ -164,10 +161,7 @@ mod tests { generated.cxx_qt_mod_contents[3], parse_quote! { impl MyObject { - #[doc = "Setter for the Q_PROPERTY "] - #[doc = "trivial_property"] - #[doc = "\n"] - #[doc = "This is an internal method used by C++ to set the value of the Q_PROPERTY in the Rust struct"] + #[doc(hidden)] pub fn set_trivial_property(&mut self, cpp: Pin<&mut MyObjectQt>, value: i32) { cpp.set_trivial_property(value); } @@ -226,10 +220,7 @@ mod tests { generated.cxx_qt_mod_contents[5], parse_quote! { impl MyObject { - #[doc = "Getter for the Q_PROPERTY "] - #[doc = "opaque_property"] - #[doc = "\n"] - #[doc = "This is an internal method used by C++ to retrieve the value of the Q_PROPERTY in the Rust struct"] + #[doc(hidden)] pub fn opaque_property<'a>(&'a self, cpp: &'a MyObjectQt) -> &'a UniquePtr { cpp.opaque_property() } @@ -280,10 +271,7 @@ mod tests { generated.cxx_qt_mod_contents[8], parse_quote! { impl MyObject { - #[doc = "Setter for the Q_PROPERTY "] - #[doc = "opaque_property"] - #[doc = "\n"] - #[doc = "This is an internal method used by C++ to set the value of the Q_PROPERTY in the Rust struct"] + #[doc(hidden)] pub fn set_opaque_property(&mut self, cpp: Pin<&mut MyObjectQt>, value: UniquePtr) { cpp.set_opaque_property(value); } @@ -342,10 +330,7 @@ mod tests { generated.cxx_qt_mod_contents[10], parse_quote! { impl MyObject { - #[doc = "Getter for the Q_PROPERTY "] - #[doc = "unsafe_property"] - #[doc = "\n"] - #[doc = "This is an internal method used by C++ to retrieve the value of the Q_PROPERTY in the Rust struct"] + #[doc(hidden)] pub fn unsafe_property<'a>(&'a self, cpp: &'a MyObjectQt) -> &'a *mut T { cpp.unsafe_property() } @@ -396,10 +381,7 @@ mod tests { generated.cxx_qt_mod_contents[13], parse_quote! { impl MyObject { - #[doc = "Setter for the Q_PROPERTY "] - #[doc = "unsafe_property"] - #[doc = "\n"] - #[doc = "This is an internal method used by C++ to set the value of the Q_PROPERTY in the Rust struct"] + #[doc(hidden)] pub fn set_unsafe_property(&mut self, cpp: Pin<&mut MyObjectQt>, value: *mut T) { cpp.set_unsafe_property(value); } diff --git a/crates/cxx-qt-gen/src/generator/rust/property/setter.rs b/crates/cxx-qt-gen/src/generator/rust/property/setter.rs index 9db646969..ba26b9d17 100644 --- a/crates/cxx-qt-gen/src/generator/rust/property/setter.rs +++ b/crates/cxx-qt-gen/src/generator/rust/property/setter.rs @@ -40,10 +40,7 @@ pub fn generate( implementation: vec![ quote! { impl #rust_struct_name_rust { - #[doc = "Setter for the Q_PROPERTY "] - #[doc = #ident_str] - #[doc = "\n"] - #[doc = "This is an internal method used by C++ to set the value of the Q_PROPERTY in the Rust struct"] + #[doc(hidden)] pub fn #setter_rust(&mut self, cpp: Pin<&mut #cpp_class_name_rust>, value: #ty) { cpp.#setter_rust(value); } diff --git a/crates/cxx-qt-gen/src/generator/rust/signals.rs b/crates/cxx-qt-gen/src/generator/rust/signals.rs index 812c7afad..a3b061885 100644 --- a/crates/cxx-qt-gen/src/generator/rust/signals.rs +++ b/crates/cxx-qt-gen/src/generator/rust/signals.rs @@ -79,6 +79,7 @@ pub fn generate_rust_signals( let fragment = RustFragmentPair { cxx_bridge: vec![quote! { unsafe extern "C++" { + #[doc(hidden)] #[rust_name = #emit_ident_rust_str] #has_unsafe fn #emit_ident_cpp(#parameter_signatures); } @@ -160,6 +161,7 @@ mod tests { &generated.cxx_mod_contents[0], quote! { unsafe extern "C++" { + #[doc(hidden)] #[rust_name = "emit_ready"] fn emitReady(self: Pin<&mut MyObjectQt>); } @@ -171,6 +173,7 @@ mod tests { &generated.cxx_mod_contents[1], quote! { unsafe extern "C++" { + #[doc(hidden)] #[rust_name = "emit_data_changed"] fn emitDataChanged(self: Pin<&mut MyObjectQt>, trivial: i32, opaque: UniquePtr); } @@ -182,6 +185,7 @@ mod tests { &generated.cxx_mod_contents[2], quote! { unsafe extern "C++" { + #[doc(hidden)] #[rust_name = "emit_unsafe_signal"] unsafe fn emitUnsafeSignal(self: Pin<&mut MyObjectQt>, param: *mut T); } @@ -193,6 +197,7 @@ mod tests { &generated.cxx_mod_contents[3], quote! { unsafe extern "C++" { + #[doc(hidden)] #[rust_name = "emit_base_name"] fn emitBaseName(self: Pin<&mut MyObjectQt>); } diff --git a/crates/cxx-qt-gen/src/writer/rust/mod.rs b/crates/cxx-qt-gen/src/writer/rust/mod.rs index 995c7a3e3..5a4c1ca52 100644 --- a/crates/cxx-qt-gen/src/writer/rust/mod.rs +++ b/crates/cxx-qt-gen/src/writer/rust/mod.rs @@ -54,6 +54,7 @@ fn cxx_bridge_common_blocks(qobject: &GeneratedRustQObject) -> Vec // SAFETY: // - Send + 'static: argument closure can be transferred to QObject thread. // - FnOnce: QMetaObject::invokeMethod() should call the function at most once. + #[doc(hidden)] #[cxx_name = "queue"] fn queue_boxed_fn( self: &#cxx_qt_thread_ident, @@ -115,6 +116,7 @@ fn cxx_qt_common_blocks(qobject: &GeneratedRustQObject) -> Vec { // to work around the cxx limitation. // https://github.com/dtolnay/cxx/issues/114 #[allow(clippy::boxed_local)] + #[doc(hidden)] fn func( obj: std::pin::Pin<&mut #cpp_struct_ident>, arg: std::boxed::Box<#cxx_qt_thread_queued_fn_ident>, @@ -127,7 +129,7 @@ fn cxx_qt_common_blocks(qobject: &GeneratedRustQObject) -> Vec { } }, quote! { - /// Generated CXX-Qt thread helper for a QObject + #[doc(hidden)] pub struct #cxx_qt_thread_queued_fn_ident { // An opaque Rust type is required to be Sized. // https://github.com/dtolnay/cxx/issues/665 @@ -231,6 +233,7 @@ pub fn write_rust(generated: &GeneratedRustBlocks) -> TokenStream { use super::#cxx_mod_ident::*; use std::pin::Pin; + #[doc(hidden)] type UniquePtr = cxx::UniquePtr; #(#cxx_qt_mod_contents)* @@ -439,6 +442,7 @@ mod tests { #[cxx_name = "qtThread"] fn qt_thread(self: &MyObjectQt) -> UniquePtr; + #[doc(hidden)] #[cxx_name = "queue"] fn queue_boxed_fn( self: &MyObjectCxxQtThread, @@ -477,6 +481,7 @@ mod tests { use super::ffi::*; use std::pin::Pin; + #[doc(hidden)] type UniquePtr = cxx::UniquePtr; use module::Struct; @@ -500,6 +505,7 @@ mod tests { F: Send + 'static, { #[allow(clippy::boxed_local)] + #[doc(hidden)] fn func( obj: std::pin::Pin<&mut MyObjectQt>, arg: std::boxed::Box, @@ -511,7 +517,7 @@ mod tests { } } - /// Generated CXX-Qt thread helper for a QObject + #[doc(hidden)] pub struct MyObjectCxxQtThreadQueuedFn { inner: std::boxed::Box) + Send>, } @@ -582,6 +588,7 @@ mod tests { #[cxx_name = "qtThread"] fn qt_thread(self: &FirstObjectQt) -> UniquePtr; + #[doc(hidden)] #[cxx_name = "queue"] fn queue_boxed_fn( self: &FirstObjectCxxQtThread, @@ -642,6 +649,7 @@ mod tests { #[cxx_name = "qtThread"] fn qt_thread(self: &SecondObjectQt) -> UniquePtr; + #[doc(hidden)] #[cxx_name = "queue"] fn queue_boxed_fn( self: &SecondObjectCxxQtThread, @@ -680,6 +688,7 @@ mod tests { use super::ffi::*; use std::pin::Pin; + #[doc(hidden)] type UniquePtr = cxx::UniquePtr; use module::Struct; @@ -703,6 +712,7 @@ mod tests { F: Send + 'static, { #[allow(clippy::boxed_local)] + #[doc(hidden)] fn func( obj: std::pin::Pin<&mut FirstObjectQt>, arg: std::boxed::Box, @@ -714,7 +724,7 @@ mod tests { } } - /// Generated CXX-Qt thread helper for a QObject + #[doc(hidden)] pub struct FirstObjectCxxQtThreadQueuedFn { inner: std::boxed::Box) + Send>, } @@ -743,6 +753,7 @@ mod tests { F: Send + 'static, { #[allow(clippy::boxed_local)] + #[doc(hidden)] fn func( obj: std::pin::Pin<&mut SecondObjectQt>, arg: std::boxed::Box, @@ -754,7 +765,7 @@ mod tests { } } - /// Generated CXX-Qt thread helper for a QObject + #[doc(hidden)] pub struct SecondObjectCxxQtThreadQueuedFn { inner: std::boxed::Box) + Send>, } diff --git a/crates/cxx-qt-gen/test_outputs/inheritance.rs b/crates/cxx-qt-gen/test_outputs/inheritance.rs index f5b174b49..88c7edb68 100644 --- a/crates/cxx-qt-gen/test_outputs/inheritance.rs +++ b/crates/cxx-qt-gen/test_outputs/inheritance.rs @@ -44,10 +44,16 @@ mod inheritance { fn has_children_wrapper(self: &MyObject, cpp: &MyObjectQt, _parent: &QModelIndex) -> bool; } unsafe extern "C++" { + #[doc = "CXX-Qt generated method which calls the C++ method"] + #[doc = "hasChildren"] + #[doc = "on the base class"] #[cxx_name = "hasChildrenCxxQtInherit"] fn has_children_super(self: &MyObjectQt, parent: &QModelIndex) -> bool; } extern "C++" { + #[doc = "CXX-Qt generated method which calls the C++ method"] + #[doc = "fetchMore"] + #[doc = "on the base class"] #[cxx_name = "fetchMoreCxxQtInherit"] unsafe fn fetch_more(self: Pin<&mut MyObjectQt>, index: &QModelIndex); } @@ -67,6 +73,7 @@ mod inheritance { #[doc = r" This allows for queueing closures onto the Qt event loop from a background thread."] #[cxx_name = "qtThread"] fn qt_thread(self: &MyObjectQt) -> UniquePtr; + #[doc(hidden)] #[cxx_name = "queue"] fn queue_boxed_fn( self: &MyObjectCxxQtThread, @@ -99,6 +106,7 @@ pub use self::cxx_qt_inheritance::*; mod cxx_qt_inheritance { use super::inheritance::*; use std::pin::Pin; + #[doc(hidden)] type UniquePtr = cxx::UniquePtr; #[derive(Default)] pub struct MyObject { @@ -122,8 +130,7 @@ mod cxx_qt_inheritance { } } impl MyObject { - #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] - #[doc = "data"] + #[doc(hidden)] pub fn data_wrapper( self: &MyObject, cpp: &MyObjectQt, @@ -139,8 +146,7 @@ mod cxx_qt_inheritance { } } impl MyObject { - #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] - #[doc = "has_children"] + #[doc(hidden)] pub fn has_children_wrapper( self: &MyObject, cpp: &MyObjectQt, @@ -163,6 +169,7 @@ mod cxx_qt_inheritance { F: Send + 'static, { #[allow(clippy::boxed_local)] + #[doc(hidden)] fn func( obj: std::pin::Pin<&mut MyObjectQt>, arg: std::boxed::Box, @@ -175,7 +182,7 @@ mod cxx_qt_inheritance { self.queue_boxed_fn(func, std::boxed::Box::new(arg)) } } - #[doc = r" Generated CXX-Qt thread helper for a QObject"] + #[doc(hidden)] pub struct MyObjectCxxQtThreadQueuedFn { inner: std::boxed::Box) + Send>, } diff --git a/crates/cxx-qt-gen/test_outputs/invokables.rs b/crates/cxx-qt-gen/test_outputs/invokables.rs index 55844f6e4..ac0c421b0 100644 --- a/crates/cxx-qt-gen/test_outputs/invokables.rs +++ b/crates/cxx-qt-gen/test_outputs/invokables.rs @@ -106,6 +106,7 @@ mod ffi { #[cxx_name = "qtThread"] fn qt_thread(self: &MyObjectQt) -> UniquePtr; + #[doc(hidden)] #[cxx_name = "queue"] fn queue_boxed_fn( self: &MyObjectCxxQtThread, @@ -144,6 +145,7 @@ mod cxx_qt_ffi { use super::ffi::*; use std::pin::Pin; + #[doc(hidden)] type UniquePtr = cxx::UniquePtr; impl MyObject { @@ -156,8 +158,7 @@ mod cxx_qt_ffi { pub struct MyObject; impl MyObject { - #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] - #[doc = "invokable"] + #[doc(hidden)] pub fn invokable_wrapper(self: &MyObject, cpp: &MyObjectQt) { cpp.invokable(); } @@ -170,8 +171,7 @@ mod cxx_qt_ffi { } impl MyObject { - #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] - #[doc = "invokable_mutable"] + #[doc(hidden)] pub fn invokable_mutable_wrapper(self: &mut MyObject, cpp: Pin<&mut MyObjectQt>) { cpp.invokable_mutable(); } @@ -184,8 +184,7 @@ mod cxx_qt_ffi { } impl MyObject { - #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] - #[doc = "invokable_parameters"] + #[doc(hidden)] pub fn invokable_parameters_wrapper( self: &MyObject, cpp: &MyObjectQt, @@ -209,8 +208,7 @@ mod cxx_qt_ffi { } impl MyObject { - #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] - #[doc = "invokable_return_opaque"] + #[doc(hidden)] pub fn invokable_return_opaque_wrapper( self: &mut MyObject, cpp: Pin<&mut MyObjectQt>, @@ -226,8 +224,7 @@ mod cxx_qt_ffi { } impl MyObject { - #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] - #[doc = "invokable_return_trivial"] + #[doc(hidden)] pub fn invokable_return_trivial_wrapper( self: &mut MyObject, cpp: Pin<&mut MyObjectQt>, @@ -243,8 +240,7 @@ mod cxx_qt_ffi { } impl MyObject { - #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] - #[doc = "invokable_final"] + #[doc(hidden)] pub fn invokable_final_wrapper(self: &MyObject, cpp: &MyObjectQt) { cpp.invokable_final(); } @@ -257,8 +253,7 @@ mod cxx_qt_ffi { } impl MyObject { - #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] - #[doc = "invokable_override"] + #[doc(hidden)] pub fn invokable_override_wrapper(self: &MyObject, cpp: &MyObjectQt) { cpp.invokable_override(); } @@ -271,8 +266,7 @@ mod cxx_qt_ffi { } impl MyObject { - #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] - #[doc = "invokable_virtual"] + #[doc(hidden)] pub fn invokable_virtual_wrapper(self: &MyObject, cpp: &MyObjectQt) { cpp.invokable_virtual(); } @@ -312,6 +306,7 @@ mod cxx_qt_ffi { F: Send + 'static, { #[allow(clippy::boxed_local)] + #[doc(hidden)] fn func( obj: std::pin::Pin<&mut MyObjectQt>, arg: std::boxed::Box, @@ -325,7 +320,7 @@ mod cxx_qt_ffi { } } - #[doc = r" Generated CXX-Qt thread helper for a QObject"] + #[doc(hidden)] pub struct MyObjectCxxQtThreadQueuedFn { inner: std::boxed::Box) + Send>, } diff --git a/crates/cxx-qt-gen/test_outputs/passthrough_and_naming.rs b/crates/cxx-qt-gen/test_outputs/passthrough_and_naming.rs index 2af5ac130..7ba888c4e 100644 --- a/crates/cxx-qt-gen/test_outputs/passthrough_and_naming.rs +++ b/crates/cxx-qt-gen/test_outputs/passthrough_and_naming.rs @@ -117,6 +117,7 @@ pub mod ffi { } unsafe extern "C++" { + #[doc(hidden)] #[rust_name = "emit_ready"] fn emitReady(self: Pin<&mut MyObjectQt>); } @@ -140,6 +141,7 @@ pub mod ffi { #[cxx_name = "qtThread"] fn qt_thread(self: &MyObjectQt) -> UniquePtr; + #[doc(hidden)] #[cxx_name = "queue"] fn queue_boxed_fn( self: &MyObjectCxxQtThread, @@ -215,6 +217,7 @@ pub mod ffi { } unsafe extern "C++" { + #[doc(hidden)] #[rust_name = "emit_ready"] fn emitReady(self: Pin<&mut SecondObjectQt>); } @@ -235,6 +238,7 @@ pub mod ffi { #[doc = r" This allows for queueing closures onto the Qt event loop from a background thread."] #[cxx_name = "qtThread"] fn qt_thread(self: &SecondObjectQt) -> UniquePtr; + #[doc(hidden)] #[cxx_name = "queue"] fn queue_boxed_fn( self: &SecondObjectCxxQtThread, @@ -271,6 +275,7 @@ mod cxx_qt_ffi { use super::ffi::*; use std::pin::Pin; + #[doc(hidden)] type UniquePtr = cxx::UniquePtr; use super::MyTrait; @@ -302,10 +307,7 @@ mod cxx_qt_ffi { } impl MyObject { - #[doc = "Getter for the Q_PROPERTY "] - #[doc = "property_name"] - #[doc = "\n"] - #[doc = "This is an internal method used by C++ to retrieve the value of the Q_PROPERTY in the Rust struct"] + #[doc(hidden)] pub fn property_name<'a>(&'a self, cpp: &'a MyObjectQt) -> &'a i32 { cpp.property_name() } @@ -333,10 +335,7 @@ mod cxx_qt_ffi { } impl MyObject { - #[doc = "Setter for the Q_PROPERTY "] - #[doc = "property_name"] - #[doc = "\n"] - #[doc = "This is an internal method used by C++ to set the value of the Q_PROPERTY in the Rust struct"] + #[doc(hidden)] pub fn set_property_name(&mut self, cpp: Pin<&mut MyObjectQt>, value: i32) { cpp.set_property_name(value); } @@ -357,8 +356,7 @@ mod cxx_qt_ffi { } impl MyObject { - #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] - #[doc = "invokable_name"] + #[doc(hidden)] pub fn invokable_name_wrapper(self: &mut MyObject, cpp: Pin<&mut MyObjectQt>) { cpp.invokable_name(); } @@ -409,6 +407,7 @@ mod cxx_qt_ffi { F: Send + 'static, { #[allow(clippy::boxed_local)] + #[doc(hidden)] fn func( obj: std::pin::Pin<&mut MyObjectQt>, arg: std::boxed::Box, @@ -422,7 +421,7 @@ mod cxx_qt_ffi { } } - #[doc = r" Generated CXX-Qt thread helper for a QObject"] + #[doc(hidden)] pub struct MyObjectCxxQtThreadQueuedFn { inner: std::boxed::Box) + Send>, } @@ -443,10 +442,7 @@ mod cxx_qt_ffi { } impl SecondObject { - #[doc = "Getter for the Q_PROPERTY "] - #[doc = "property_name"] - #[doc = "\n"] - #[doc = "This is an internal method used by C++ to retrieve the value of the Q_PROPERTY in the Rust struct"] + #[doc(hidden)] pub fn property_name<'a>(&'a self, cpp: &'a SecondObjectQt) -> &'a i32 { cpp.property_name() } @@ -473,10 +469,7 @@ mod cxx_qt_ffi { } impl SecondObject { - #[doc = "Setter for the Q_PROPERTY "] - #[doc = "property_name"] - #[doc = "\n"] - #[doc = "This is an internal method used by C++ to set the value of the Q_PROPERTY in the Rust struct"] + #[doc(hidden)] pub fn set_property_name(&mut self, cpp: Pin<&mut SecondObjectQt>, value: i32) { cpp.set_property_name(value); } @@ -497,8 +490,7 @@ mod cxx_qt_ffi { } impl SecondObject { - #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] - #[doc = "invokable_name"] + #[doc(hidden)] pub fn invokable_name_wrapper(self: &mut SecondObject, cpp: Pin<&mut SecondObjectQt>) { cpp.invokable_name(); } @@ -537,6 +529,7 @@ mod cxx_qt_ffi { F: Send + 'static, { #[allow(clippy::boxed_local)] + #[doc(hidden)] fn func( obj: std::pin::Pin<&mut SecondObjectQt>, arg: std::boxed::Box, @@ -550,7 +543,7 @@ mod cxx_qt_ffi { } } - #[doc = r" Generated CXX-Qt thread helper for a QObject"] + #[doc(hidden)] pub struct SecondObjectCxxQtThreadQueuedFn { inner: std::boxed::Box) + Send>, } diff --git a/crates/cxx-qt-gen/test_outputs/properties.rs b/crates/cxx-qt-gen/test_outputs/properties.rs index 5d999c47d..93bacafba 100644 --- a/crates/cxx-qt-gen/test_outputs/properties.rs +++ b/crates/cxx-qt-gen/test_outputs/properties.rs @@ -115,6 +115,7 @@ mod ffi { #[cxx_name = "qtThread"] fn qt_thread(self: &MyObjectQt) -> UniquePtr; + #[doc(hidden)] #[cxx_name = "queue"] fn queue_boxed_fn( self: &MyObjectCxxQtThread, @@ -153,6 +154,7 @@ mod cxx_qt_ffi { use super::ffi::*; use std::pin::Pin; + #[doc(hidden)] type UniquePtr = cxx::UniquePtr; #[derive(Default)] @@ -165,10 +167,7 @@ mod cxx_qt_ffi { } impl MyObject { - #[doc = "Getter for the Q_PROPERTY "] - #[doc = "primitive"] - #[doc = "\n"] - #[doc = "This is an internal method used by C++ to retrieve the value of the Q_PROPERTY in the Rust struct"] + #[doc(hidden)] pub fn primitive<'a>(&'a self, cpp: &'a MyObjectQt) -> &'a i32 { cpp.primitive() } @@ -196,10 +195,7 @@ mod cxx_qt_ffi { } impl MyObject { - #[doc = "Setter for the Q_PROPERTY "] - #[doc = "primitive"] - #[doc = "\n"] - #[doc = "This is an internal method used by C++ to set the value of the Q_PROPERTY in the Rust struct"] + #[doc(hidden)] pub fn set_primitive(&mut self, cpp: Pin<&mut MyObjectQt>, value: i32) { cpp.set_primitive(value); } @@ -220,10 +216,7 @@ mod cxx_qt_ffi { } impl MyObject { - #[doc = "Getter for the Q_PROPERTY "] - #[doc = "trivial"] - #[doc = "\n"] - #[doc = "This is an internal method used by C++ to retrieve the value of the Q_PROPERTY in the Rust struct"] + #[doc(hidden)] pub fn trivial<'a>(&'a self, cpp: &'a MyObjectQt) -> &'a QPoint { cpp.trivial() } @@ -251,10 +244,7 @@ mod cxx_qt_ffi { } impl MyObject { - #[doc = "Setter for the Q_PROPERTY "] - #[doc = "trivial"] - #[doc = "\n"] - #[doc = "This is an internal method used by C++ to set the value of the Q_PROPERTY in the Rust struct"] + #[doc(hidden)] pub fn set_trivial(&mut self, cpp: Pin<&mut MyObjectQt>, value: QPoint) { cpp.set_trivial(value); } @@ -275,10 +265,7 @@ mod cxx_qt_ffi { } impl MyObject { - #[doc = "Getter for the Q_PROPERTY "] - #[doc = "opaque"] - #[doc = "\n"] - #[doc = "This is an internal method used by C++ to retrieve the value of the Q_PROPERTY in the Rust struct"] + #[doc(hidden)] pub fn opaque<'a>(&'a self, cpp: &'a MyObjectQt) -> &'a UniquePtr { cpp.opaque() } @@ -306,10 +293,7 @@ mod cxx_qt_ffi { } impl MyObject { - #[doc = "Setter for the Q_PROPERTY "] - #[doc = "opaque"] - #[doc = "\n"] - #[doc = "This is an internal method used by C++ to set the value of the Q_PROPERTY in the Rust struct"] + #[doc(hidden)] pub fn set_opaque(&mut self, cpp: Pin<&mut MyObjectQt>, value: UniquePtr) { cpp.set_opaque(value); } @@ -379,6 +363,7 @@ mod cxx_qt_ffi { F: Send + 'static, { #[allow(clippy::boxed_local)] + #[doc(hidden)] fn func( obj: std::pin::Pin<&mut MyObjectQt>, arg: std::boxed::Box, @@ -392,7 +377,7 @@ mod cxx_qt_ffi { } } - #[doc = r" Generated CXX-Qt thread helper for a QObject"] + #[doc(hidden)] pub struct MyObjectCxxQtThreadQueuedFn { inner: std::boxed::Box) + Send>, } diff --git a/crates/cxx-qt-gen/test_outputs/signals.rs b/crates/cxx-qt-gen/test_outputs/signals.rs index 751a887dd..125bd5d29 100644 --- a/crates/cxx-qt-gen/test_outputs/signals.rs +++ b/crates/cxx-qt-gen/test_outputs/signals.rs @@ -39,11 +39,13 @@ mod ffi { } unsafe extern "C++" { + #[doc(hidden)] #[rust_name = "emit_ready"] fn emitReady(self: Pin<&mut MyObjectQt>); } unsafe extern "C++" { + #[doc(hidden)] #[rust_name = "emit_data_changed"] fn emitDataChanged( self: Pin<&mut MyObjectQt>, @@ -55,6 +57,7 @@ mod ffi { } unsafe extern "C++" { + #[doc(hidden)] #[rust_name = "emit_new_data"] fn emitNewData( self: Pin<&mut MyObjectQt>, @@ -84,6 +87,7 @@ mod ffi { #[cxx_name = "qtThread"] fn qt_thread(self: &MyObjectQt) -> UniquePtr; + #[doc(hidden)] #[cxx_name = "queue"] fn queue_boxed_fn( self: &MyObjectCxxQtThread, @@ -122,14 +126,14 @@ mod cxx_qt_ffi { use super::ffi::*; use std::pin::Pin; + #[doc(hidden)] type UniquePtr = cxx::UniquePtr; #[derive(Default)] pub struct MyObject; impl MyObject { - #[doc = "Generated CXX-Qt wrapper method for the Q_INVOKABLE"] - #[doc = "invokable"] + #[doc(hidden)] pub fn invokable_wrapper(self: &mut MyObject, cpp: Pin<&mut MyObjectQt>) { cpp.invokable(); } @@ -196,6 +200,7 @@ mod cxx_qt_ffi { F: Send + 'static, { #[allow(clippy::boxed_local)] + #[doc(hidden)] fn func( obj: std::pin::Pin<&mut MyObjectQt>, arg: std::boxed::Box, @@ -209,7 +214,7 @@ mod cxx_qt_ffi { } } - #[doc = r" Generated CXX-Qt thread helper for a QObject"] + #[doc(hidden)] pub struct MyObjectCxxQtThreadQueuedFn { inner: std::boxed::Box) + Send>, } From 558d99ae2c39074b4aa8cd3c7b29a895e445131e Mon Sep 17 00:00:00 2001 From: Andrew Hayzen Date: Mon, 17 Apr 2023 13:42:20 +0100 Subject: [PATCH 3/7] qml_features: enable deny(missing_docs) This ensures we don't regress with any missing docs for generated public items, related to #517 --- examples/cargo_without_cmake/src/main.rs | 8 ++++- examples/qml_features/rust/src/containers.rs | 23 ++++++++++++-- .../rust/src/custom_base_class.rs | 25 +++++++++++++++- examples/qml_features/rust/src/invokables.rs | 5 ++++ examples/qml_features/rust/src/lib.rs | 30 +++++++++++-------- .../rust/src/multiple_qobjects.rs | 17 ++++++++++- .../qml_features/rust/src/nested_qobjects.rs | 22 ++++++++++++-- examples/qml_features/rust/src/properties.rs | 14 ++++++++- .../qml_features/rust/src/serialisation.rs | 21 ++++++++++--- examples/qml_features/rust/src/signals.rs | 22 ++++++++++++-- examples/qml_features/rust/src/singleton.rs | 6 ++++ examples/qml_features/rust/src/threading.rs | 12 ++++++-- examples/qml_features/rust/src/types.rs | 16 +++++++++- examples/qml_features/rust/src/uncreatable.rs | 5 ++++ examples/qml_minimal/rust/src/cxxqt_object.rs | 7 ++++- 15 files changed, 202 insertions(+), 31 deletions(-) diff --git a/examples/cargo_without_cmake/src/main.rs b/examples/cargo_without_cmake/src/main.rs index 91a07f61d..8e487f78e 100644 --- a/examples/cargo_without_cmake/src/main.rs +++ b/examples/cargo_without_cmake/src/main.rs @@ -5,8 +5,14 @@ // // SPDX-License-Identifier: MIT OR Apache-2.0 +//! This example provides demostrations of building a Cargo only CXX-Qt application + +// Use this crate to test that missing_docs works with our generated code for a Cargo only build +#![deny(missing_docs)] + +/// A module for our Rust defined QObject // ANCHOR: book_cargo_imports -mod cxxqt_object; +pub mod cxxqt_object; use cxx_qt_lib::{QGuiApplication, QQmlApplicationEngine, QUrl}; // ANCHOR_END: book_cargo_imports diff --git a/examples/qml_features/rust/src/containers.rs b/examples/qml_features/rust/src/containers.rs index f5f93ac0b..51dd23f28 100644 --- a/examples/qml_features/rust/src/containers.rs +++ b/examples/qml_features/rust/src/containers.rs @@ -3,25 +3,38 @@ // // SPDX-License-Identifier: MIT OR Apache-2.0 +//! This example shows how container types can be used + +/// A CXX-Qt bridge which shows container types can be used #[cxx_qt::bridge(cxx_file_stem = "rust_containers")] -mod ffi { +pub mod ffi { unsafe extern "C++" { include!("cxx-qt-lib/qhash.h"); + /// QHash from cxx_qt_lib type QHash_QString_QVariant = cxx_qt_lib::QHash; include!("cxx-qt-lib/qlist.h"); + /// QList from cxx_qt_lib type QList_i32 = cxx_qt_lib::QList; include!("cxx-qt-lib/qmap.h"); + /// QMap from cxx_qt_lib type QMap_QString_QVariant = cxx_qt_lib::QMap; include!("cxx-qt-lib/qset.h"); + /// QSet from cxx_qt_lib type QSet_i32 = cxx_qt_lib::QSet; include!("cxx-qt-lib/qstring.h"); + /// QString from cxx_qt_lib type QString = cxx_qt_lib::QString; include!("cxx-qt-lib/qvariant.h"); + /// QVariant from cxx_qt_lib type QVariant = cxx_qt_lib::QVariant; include!("cxx-qt-lib/qvector.h"); + /// QVector from cxx_qt_lib type QVector_i32 = cxx_qt_lib::QVector; } + /// A QObject which stores container types internally + /// + /// Then it has Q_PROPERTYs which expose a string of the container to be show in QML #[cxx_qt::qobject(qml_uri = "com.kdab.cxx_qt.demo", qml_version = "1.0")] #[derive(Default)] pub struct RustContainers { @@ -44,6 +57,7 @@ mod ffi { } impl qobject::RustContainers { + /// Reset all the container types #[qinvokable] pub fn reset(mut self: Pin<&mut Self>) { self.as_mut().set_hash(QHash_QString_QVariant::default()); @@ -55,6 +69,7 @@ mod ffi { self.update_strings(); } + /// Append the given number to the vector container #[qinvokable] pub fn append_vector(mut self: Pin<&mut Self>, value: i32) { self.as_mut().vector_mut().append(value); @@ -62,6 +77,7 @@ mod ffi { self.update_strings(); } + /// Append the given number to the list container #[qinvokable] pub fn append_list(mut self: Pin<&mut Self>, value: i32) { self.as_mut().list_mut().append(value); @@ -69,6 +85,7 @@ mod ffi { self.update_strings(); } + /// Insert the given number into the set container #[qinvokable] pub fn insert_set(mut self: Pin<&mut Self>, value: i32) { self.as_mut().set_mut().insert(value); @@ -76,6 +93,7 @@ mod ffi { self.update_strings(); } + /// Insert the given string and variant to the hash container #[qinvokable] pub fn insert_hash(mut self: Pin<&mut Self>, key: QString, value: QVariant) { self.as_mut().hash_mut().insert(key, value); @@ -83,6 +101,7 @@ mod ffi { self.update_strings(); } + /// Insert the given string and variant to the map container #[qinvokable] pub fn insert_map(mut self: Pin<&mut Self>, key: QString, value: QVariant) { self.as_mut().map_mut().insert(key, value); @@ -90,7 +109,7 @@ mod ffi { self.update_strings(); } - pub fn update_strings(mut self: Pin<&mut Self>) { + fn update_strings(mut self: Pin<&mut Self>) { let hash_items = self .as_ref() .hash() diff --git a/examples/qml_features/rust/src/custom_base_class.rs b/examples/qml_features/rust/src/custom_base_class.rs index 1ad351371..f4632cad1 100644 --- a/examples/qml_features/rust/src/custom_base_class.rs +++ b/examples/qml_features/rust/src/custom_base_class.rs @@ -3,27 +3,35 @@ // // SPDX-License-Identifier: MIT OR Apache-2.0 +//! This example shows how a custom base class and inheritance can be used + +/// A CXX-Qt bridge which shows a custom base class and inheritance can be used // ANCHOR: book_macro_code #[cxx_qt::bridge(cxx_file_stem = "custom_base_class")] -mod ffi { +pub mod ffi { // ANCHOR: book_base_include unsafe extern "C++" { include!(< QAbstractListModel >); // ANCHOR_END: book_base_include include!("cxx-qt-lib/qhash.h"); + /// QHash from cxx_qt_lib type QHash_i32_QByteArray = cxx_qt_lib::QHash; include!("cxx-qt-lib/qvariant.h"); + /// QVariant from cxx_qt_lib type QVariant = cxx_qt_lib::QVariant; include!("cxx-qt-lib/qmodelindex.h"); + /// QModelIndex from cxx_qt_lib type QModelIndex = cxx_qt_lib::QModelIndex; include!("cxx-qt-lib/qvector.h"); + /// QVector from cxx_qt_lib type QVector_i32 = cxx_qt_lib::QVector; } + /// A struct which will derive from a QAbstractListModel // ANCHOR: book_inherit_qalm // ANCHOR: book_qobject_base #[cxx_qt::qobject( @@ -39,24 +47,31 @@ mod ffi { } // ANCHOR_END: book_inherit_qalm + /// The signals for our QAbstractListModel struct // ANCHOR: book_qsignals_inherit #[cxx_qt::qsignals(CustomBaseClass)] pub enum Signals<'a> { + /// Inherit the DataChanged signal from the QAbstractListModel base class #[inherit] DataChanged { + /// Top left affected index top_left: &'a QModelIndex, + /// Bottom right affected index bottom_right: &'a QModelIndex, + /// Roles that have been modified roles: &'a QVector_i32, }, } // ANCHOR_END: book_qsignals_inherit impl qobject::CustomBaseClass { + /// Add a new row to the QAbstractListModel on the current thread #[qinvokable] pub fn add(self: Pin<&mut Self>) { self.add_cpp_context(); } + /// On a background thread add a given number of rows to the QAbstractListModel #[qinvokable] pub fn add_on_thread(self: Pin<&mut Self>, mut counter: i32) { let qt_thread = self.qt_thread(); @@ -92,6 +107,7 @@ mod ffi { } } + /// Clear the rows in the QAbstractListModel // ANCHOR: book_inherit_clear #[qinvokable] pub fn clear(mut self: Pin<&mut Self>) { @@ -104,6 +120,7 @@ mod ffi { } // ANCHOR_END: book_inherit_clear + /// Multiply the number in the row with the given index by the given factor #[qinvokable] pub fn multiply(mut self: Pin<&mut Self>, index: i32, factor: f64) { if let Some((_, value)) = self.as_mut().vector_mut().get_mut(index as usize) { @@ -121,6 +138,7 @@ mod ffi { } } + /// Remove the row with the given index #[qinvokable] pub fn remove(mut self: Pin<&mut Self>, index: i32) { if index < 0 || (index as usize) >= self.vector().len() { @@ -178,7 +196,9 @@ mod ffi { // QAbstractListModel implementation impl qobject::CustomBaseClass { + /// i32 representing the id role pub const ID_ROLE: i32 = 0; + /// i32 representing the value role pub const VALUE_ROLE: i32 = 1; // ANCHOR: book_inherit_data @@ -196,6 +216,7 @@ mod ffi { } // ANCHOR_END: book_inherit_data + /// Return whether the base class can fetch more // ANCHOR: book_inherit_can_fetch_more // Example of overriding a C++ virtual method and calling the base class implementation. #[qinvokable(cxx_override)] @@ -204,6 +225,7 @@ mod ffi { } // ANCHOR_END: book_inherit_can_fetch_more + /// Return the role names for the QAbstractListModel #[qinvokable(cxx_override)] pub fn role_names(&self) -> QHash_i32_QByteArray { let mut roles = QHash_i32_QByteArray::default(); @@ -212,6 +234,7 @@ mod ffi { roles } + /// Return the row count for the QAbstractListModel #[qinvokable(cxx_override)] pub fn row_count(&self, _parent: &QModelIndex) -> i32 { self.rust().vector.len() as i32 diff --git a/examples/qml_features/rust/src/invokables.rs b/examples/qml_features/rust/src/invokables.rs index 7597b7c65..201135131 100644 --- a/examples/qml_features/rust/src/invokables.rs +++ b/examples/qml_features/rust/src/invokables.rs @@ -3,14 +3,19 @@ // // SPDX-License-Identifier: MIT OR Apache-2.0 +//! This example shows how a Q_INVOKABLE can be used + +/// A CXX-Qt bridge which shows how a Q_INVOKABLE can be used // ANCHOR: book_macro_code #[cxx_qt::bridge(cxx_file_stem = "rust_invokables")] pub mod ffi { unsafe extern "C++" { include!("cxx-qt-lib/qcolor.h"); + /// QColor from cxx_qt_lib type QColor = cxx_qt_lib::QColor; } + /// A QObject which has Q_INVOKABLEs #[cxx_qt::qobject(qml_uri = "com.kdab.cxx_qt.demo", qml_version = "1.0")] pub struct RustInvokables { red: f32, diff --git a/examples/qml_features/rust/src/lib.rs b/examples/qml_features/rust/src/lib.rs index bfe9c5b47..912f55de8 100644 --- a/examples/qml_features/rust/src/lib.rs +++ b/examples/qml_features/rust/src/lib.rs @@ -4,15 +4,21 @@ // // SPDX-License-Identifier: MIT OR Apache-2.0 -mod containers; -mod custom_base_class; -mod invokables; -mod multiple_qobjects; -mod nested_qobjects; -mod properties; -mod serialisation; -mod signals; -mod singleton; -mod threading; -mod types; -mod uncreatable; +// Use this crate to test that missing_docs works with our generated code +#![deny(missing_docs)] + +//! This example provides demostrations of most of the features of CXX-Qt +//! split into separate modules + +pub mod containers; +pub mod custom_base_class; +pub mod invokables; +pub mod multiple_qobjects; +pub mod nested_qobjects; +pub mod properties; +pub mod serialisation; +pub mod signals; +pub mod singleton; +pub mod threading; +pub mod types; +pub mod uncreatable; diff --git a/examples/qml_features/rust/src/multiple_qobjects.rs b/examples/qml_features/rust/src/multiple_qobjects.rs index 79e0ecd5e..8e421971e 100644 --- a/examples/qml_features/rust/src/multiple_qobjects.rs +++ b/examples/qml_features/rust/src/multiple_qobjects.rs @@ -3,15 +3,21 @@ // // SPDX-License-Identifier: MIT OR Apache-2.0 +//! This example shows how multiple QObjects can be defined in one module + +/// A CXX-Qt bridge which shows multiple QObjects can be defined in one module #[cxx_qt::bridge(cxx_file_stem = "multiple_qobjects")] -mod ffi { +pub mod ffi { unsafe extern "C++" { include!("cxx-qt-lib/qcolor.h"); + /// QColor from cxx_qt_lib type QColor = cxx_qt_lib::QColor; include!("cxx-qt-lib/qurl.h"); + /// QUrl from cxx_qt_lib type QUrl = cxx_qt_lib::QUrl; } + /// The first QObject #[cxx_qt::qobject(qml_uri = "com.kdab.cxx_qt.demo", qml_version = "1.0")] pub struct FirstObject { #[qproperty] @@ -29,13 +35,17 @@ mod ffi { } } + /// Signals for the first QObject #[cxx_qt::qsignals(FirstObject)] pub enum FirstSignals { + /// Accepted Q_SIGNAL Accepted, + /// Rejected Q_SIGNAL Rejected, } impl qobject::FirstObject { + /// A Q_INVOKABLE on the first QObject which increments a counter #[qinvokable] pub fn increment(mut self: Pin<&mut Self>) { let new_value = self.as_ref().counter() + 1; @@ -51,6 +61,7 @@ mod ffi { } } + /// The second QObject #[cxx_qt::qobject(qml_uri = "com.kdab.cxx_qt.demo", qml_version = "1.0")] pub struct SecondObject { #[qproperty] @@ -68,13 +79,17 @@ mod ffi { } } + /// Signals for the second QObject #[cxx_qt::qsignals(SecondObject)] pub enum SecondSignals { + /// Accepted Q_SIGNAL Accepted, + /// Rejected Q_SIGNAL Rejected, } impl qobject::SecondObject { + /// A Q_INVOKABLE on the second QObject which increments a counter #[qinvokable] pub fn increment(mut self: Pin<&mut Self>) { let new_value = self.as_ref().counter() + 1; diff --git a/examples/qml_features/rust/src/nested_qobjects.rs b/examples/qml_features/rust/src/nested_qobjects.rs index 834ccc6ba..f1e77ec67 100644 --- a/examples/qml_features/rust/src/nested_qobjects.rs +++ b/examples/qml_features/rust/src/nested_qobjects.rs @@ -3,16 +3,21 @@ // // SPDX-License-Identifier: MIT OR Apache-2.0 +//! This example shows how a pointer from one Rust defined QObject to another Rust defined QObject can be used + +/// A CXX-Qt bridge which shows how a pointer from one Rust defined QObject to another Rust defined QObject can be used // ANCHOR: book_macro_code #[cxx_qt::bridge(cxx_file_stem = "nested_qobjects")] -mod ffi { +pub mod ffi { // ANCHOR: book_extern_block unsafe extern "C++" { #[cxx_name = "InnerObject"] + /// THe C++ part of the InnerObject so that it can be referred to type CxxInnerObject = super::qobject::InnerObject; } // ANCHOR_END: book_extern_block + /// The inner QObject #[cxx_qt::qobject(qml_uri = "com.kdab.cxx_qt.demo", qml_version = "1.0")] #[derive(Default)] pub struct InnerObject { @@ -20,6 +25,7 @@ mod ffi { counter: i32, } + /// The outer QObject which has a Q_PROPERTY to the inner QObject #[cxx_qt::qobject(qml_uri = "com.kdab.cxx_qt.demo", qml_version = "1.0")] pub struct OuterObject { #[qproperty] @@ -34,14 +40,23 @@ mod ffi { } } + /// Signals for the outer QObject #[cxx_qt::qsignals(OuterObject)] pub enum OuterSignals { - Called { inner: *mut CxxInnerObject }, + /// A signal showing how to refer to another QObject as an argument + Called { + /// Inner QObject being referred to + inner: *mut CxxInnerObject, + }, } impl qobject::OuterObject { + /// Print the count of the given inner QObject + // + // This method needs to be unsafe otherwise clippy complains that the + // public method might dereference the raw pointer. #[qinvokable] - pub fn print_count(self: Pin<&mut Self>, inner: *mut CxxInnerObject) { + pub unsafe fn print_count(self: Pin<&mut Self>, inner: *mut CxxInnerObject) { if let Some(inner) = unsafe { inner.as_ref() } { println!("Inner object's counter property: {}", inner.counter()); } @@ -49,6 +64,7 @@ mod ffi { self.emit(OuterSignals::Called { inner }); } + /// Reset the cont of the inner QObject stored in the Q_PROPERTY #[qinvokable] pub fn reset(self: Pin<&mut Self>) { // We need to convert the *mut T to a Pin<&mut T> so that we can reach the methods diff --git a/examples/qml_features/rust/src/properties.rs b/examples/qml_features/rust/src/properties.rs index def7d1d66..5d21fd750 100644 --- a/examples/qml_features/rust/src/properties.rs +++ b/examples/qml_features/rust/src/properties.rs @@ -3,27 +3,37 @@ // // SPDX-License-Identifier: MIT OR Apache-2.0 +//! This example shows how a Q_PROPERTY can be used + +/// A CXX-Qt bridge which shows how a Q_PROPERTY can be used #[cxx_qt::bridge(cxx_file_stem = "rust_properties")] -mod ffi { +pub mod ffi { unsafe extern "C++" { include!("cxx-qt-lib/qstring.h"); + /// QString from cxx_qt_lib type QString = cxx_qt_lib::QString; include!("cxx-qt-lib/qurl.h"); + /// QUrl from cxx_qt_lib type QUrl = cxx_qt_lib::QUrl; } + /// A QObject which has Q_PROPERTYs // ANCHOR: book_properties_struct #[cxx_qt::qobject(qml_uri = "com.kdab.cxx_qt.demo", qml_version = "1.0")] pub struct RustProperties { + /// A connected Q_PROPERTY #[qproperty] connected: bool, + /// A connected_url Q_PROPERTY #[qproperty] connected_url: QUrl, + /// A previous_connected_url Q_PROPERTY #[qproperty] previous_connected_url: QUrl, + /// A status_message Q_PROPERTY #[qproperty] status_message: QString, } @@ -43,6 +53,7 @@ mod ffi { // ANCHOR_END: book_properties_default impl qobject::RustProperties { + /// Connect to the given url #[qinvokable] pub fn connect(mut self: Pin<&mut Self>, mut url: QUrl) { // Check that the url starts with kdab @@ -66,6 +77,7 @@ mod ffi { } } + /// Disconnect from the stored url #[qinvokable] pub fn disconnect(mut self: Pin<&mut Self>) { self.as_mut().set_connected(false); diff --git a/examples/qml_features/rust/src/serialisation.rs b/examples/qml_features/rust/src/serialisation.rs index 975cb6320..d7639fee9 100644 --- a/examples/qml_features/rust/src/serialisation.rs +++ b/examples/qml_features/rust/src/serialisation.rs @@ -4,12 +4,13 @@ // // SPDX-License-Identifier: MIT OR Apache-2.0 +//! This example shows how a serialisation can be used + // ANCHOR: book_macro_code use serde::{Deserialize, Serialize}; -// TODO: once Qt types support serde again, the Serialisation struct can be used -// https://github.com/KDAB/cxx-qt/issues/292 +/// A struct representating our serialised form #[derive(Deserialize, Serialize)] pub struct DataSerde { number: i32, @@ -25,26 +26,36 @@ impl From<&Serialisation> for DataSerde { } } +/// A CXX-Qt bridge which shows how a serialisation can be used #[cxx_qt::bridge(cxx_file_stem = "serialisation")] -mod ffi { +pub mod ffi { use super::DataSerde; unsafe extern "C++" { include!("cxx-qt-lib/qstring.h"); + /// QString from cxx_qt_lib type QString = cxx_qt_lib::QString; } + /// A QObject which can be serialised #[cxx_qt::qobject(qml_uri = "com.kdab.cxx_qt.demo", qml_version = "1.0")] pub struct Serialisation { + /// The number Q_PROPERTY #[qproperty] pub number: i32, + /// The string Q_PROPERTY #[qproperty] pub string: QString, } + /// Signals for the QObject #[cxx_qt::qsignals(Serialisation)] pub enum Connection { - Error { message: QString }, + /// An error signal + Error { + /// The message of the error + message: QString, + }, } impl Default for Serialisation { @@ -65,6 +76,7 @@ mod ffi { } impl qobject::Serialisation { + /// Retrieve the JSON form of this QObject #[qinvokable] pub fn as_json_str(self: Pin<&mut Self>) -> QString { let data_serde = DataSerde::from(self.rust()); @@ -79,6 +91,7 @@ mod ffi { } } + /// From a given JSON string try to load values for the Q_PROPERTYs // ANCHOR: book_grab_values #[qinvokable] pub fn from_json_str(mut self: Pin<&mut Self>, string: &QString) { diff --git a/examples/qml_features/rust/src/signals.rs b/examples/qml_features/rust/src/signals.rs index 611e3be13..1a3c9648c 100644 --- a/examples/qml_features/rust/src/signals.rs +++ b/examples/qml_features/rust/src/signals.rs @@ -3,25 +3,41 @@ // // SPDX-License-Identifier: MIT OR Apache-2.0 +//! This example shows how a Q_SIGNAL can be used + +/// A CXX-Qt bridge which shows how a Q_SIGNAL can be used // ANCHOR: book_macro_code #[cxx_qt::bridge(cxx_file_stem = "rust_signals")] pub mod ffi { unsafe extern "C++" { include!("cxx-qt-lib/qstring.h"); + /// QString from cxx_qt_lib type QString = cxx_qt_lib::QString; include!("cxx-qt-lib/qurl.h"); + /// QUrl from cxx_qt_lib type QUrl = cxx_qt_lib::QUrl; } + /// Q_SIGNALs for the QObject // ANCHOR: book_signals_enum #[cxx_qt::qsignals(RustSignals)] pub enum Connection<'a> { - Connected { url: &'a QUrl }, + /// A Q_SIGNAL emitted when a connection occurs + Connected { + /// The url for the connection + url: &'a QUrl, + }, + /// A Q_SIGNAL emitted when a disconnect occurs Disconnected, - Error { message: QString }, + /// A Q_SIGNAL emitted when an error occurs + Error { + /// The message of the error + message: QString, + }, } // ANCHOR_END: book_signals_enum + /// A QObject which has Q_SIGNALs // ANCHOR: book_signals_struct #[cxx_qt::qobject(qml_uri = "com.kdab.cxx_qt.demo", qml_version = "1.0")] #[derive(Default)] @@ -30,6 +46,7 @@ pub mod ffi { // ANCHOR: book_rust_obj_impl impl qobject::RustSignals { + /// Connect to the given url #[qinvokable] pub fn connect(mut self: Pin<&mut Self>, url: &QUrl) { // Check that the url starts with kdab @@ -44,6 +61,7 @@ pub mod ffi { } } + /// Disconnect #[qinvokable] pub fn disconnect(mut self: Pin<&mut Self>) { // Emit a signal to QML stating that we have disconnected diff --git a/examples/qml_features/rust/src/singleton.rs b/examples/qml_features/rust/src/singleton.rs index 4c3c55725..c90ca2aa1 100644 --- a/examples/qml_features/rust/src/singleton.rs +++ b/examples/qml_features/rust/src/singleton.rs @@ -3,17 +3,23 @@ // // SPDX-License-Identifier: MIT OR Apache-2.0 +//! This example shows how a QML_SINGLETON can be used + +/// A CXX-Qt bridge which shows how a QML_SINGLETON can be used // ANCHOR: book_macro_code #[cxx_qt::bridge(cxx_file_stem = "rust_singleton")] pub mod ffi { + /// A QObject which is a QML_SINGLETON #[cxx_qt::qobject(qml_uri = "com.kdab.cxx_qt.demo", qml_version = "1.0", qml_singleton)] #[derive(Default)] pub struct RustSingleton { + /// A Q_PROPERTY with a persistent value #[qproperty] persistent_value: i32, } impl qobject::RustSingleton { + /// Increment the persistent value Q_PROPERTY of the QML_SINGLETON #[qinvokable] pub fn increment(self: Pin<&mut Self>) { let new_value = self.persistent_value() + 1; diff --git a/examples/qml_features/rust/src/threading.rs b/examples/qml_features/rust/src/threading.rs index 113ef9daf..13aa9a8de 100644 --- a/examples/qml_features/rust/src/threading.rs +++ b/examples/qml_features/rust/src/threading.rs @@ -3,23 +3,31 @@ // // SPDX-License-Identifier: MIT OR Apache-2.0 +//! This example shows how a threading can be used + +/// A CXX-Qt bridge which shows how a threading can be used // ANCHOR: book_macro_code // ANCHOR: book_namespace_macro #[cxx_qt::bridge(cxx_file_stem = "threading_website", namespace = "cxx_qt::website")] -mod ffi { +pub mod ffi { // ANCHOR_END: book_namespace_macro #[namespace = ""] unsafe extern "C++" { include!("cxx-qt-lib/qstring.h"); - include!("cxx-qt-lib/qurl.h"); + /// QString from cxx_qt_lib type QString = cxx_qt_lib::QString; + include!("cxx-qt-lib/qurl.h"); + /// QUrl from cxx_qt_lib type QUrl = cxx_qt_lib::QUrl; } + /// A QObject which has threading #[cxx_qt::qobject(qml_uri = "com.kdab.cxx_qt.demo", qml_version = "1.0")] pub struct ThreadingWebsite { + /// The title Q_PROPERTY #[qproperty] title: QString, + /// The url Q_PROPERTY #[qproperty] url: QUrl, diff --git a/examples/qml_features/rust/src/types.rs b/examples/qml_features/rust/src/types.rs index b12a06354..c05e32a75 100644 --- a/examples/qml_features/rust/src/types.rs +++ b/examples/qml_features/rust/src/types.rs @@ -3,6 +3,9 @@ // // SPDX-License-Identifier: MIT OR Apache-2.0 +//! This example shows how a custom type can be used with a QVariant + +/// A struct which is a custom type we want to use with a QVariant // ANCHOR: book_macro_code #[repr(C)] pub struct CustomStruct { @@ -30,23 +33,29 @@ impl cxx_qt_lib::QVariantValue for ffi::CustomStruct { } // ANCHOR_END: book_qvariantvalue_impl +/// A CXX-Qt bridge which shows how a custom type can be used with a QVariant // ANCHOR: book_cxx_file_stem #[cxx_qt::bridge(cxx_file_stem = "types")] -mod ffi { +pub mod ffi { // ANCHOR_END: book_cxx_file_stem unsafe extern "C++" { include!("cxx-qt-lib/qpoint.h"); + /// QPointF from cxx_qt_lib type QPointF = cxx_qt_lib::QPointF; include!("cxx-qt-lib/qurl.h"); + /// QUrl from cxx_qt_lib type QUrl = cxx_qt_lib::QUrl; include!("cxx-qt-lib/qvariant.h"); + /// QVariant from cxx_qt_lib type QVariant = cxx_qt_lib::QVariant; } unsafe extern "C++" { include!("custom_object.h"); + /// CustomStruct which is a custom C++ type type CustomStruct = super::CustomStruct; + /// Return if the given QVariant can be converted into a CustomStruct #[rust_name = "qvariant_can_convert_custom_type"] fn qvariantCanConvertCustomStruct(variant: &QVariant) -> bool; } @@ -56,12 +65,15 @@ mod ffi { unsafe extern "C++" { include!("cxx-qt-lib/qvariant.h"); + /// Construct a QVariant of CustomStruct #[rust_name = "qvariant_construct_custom_type"] fn qvariantConstruct(value: &CustomStruct) -> QVariant; + /// Retrieve the CustomStruct or default from a QVariant #[rust_name = "qvariant_value_or_default_custom_type"] fn qvariantValueOrDefault(variant: &QVariant) -> CustomStruct; } + /// A QObject which shows custom types #[cxx_qt::qobject(qml_uri = "com.kdab.cxx_qt.demo", qml_version = "1.0")] pub struct Types { #[qproperty] @@ -86,6 +98,7 @@ mod ffi { } impl qobject::Types { + /// Load the value from a QVariant #[qinvokable] pub fn load_from_variant(self: Pin<&mut Self>, variant: &QVariant) { if let Some(boolean) = variant.value::() { @@ -101,6 +114,7 @@ mod ffi { } } + /// Toggle the boolean Q_PROPERTY #[qinvokable] pub fn toggle_boolean(self: Pin<&mut Self>) { let new_boolean = !self.as_ref().boolean(); diff --git a/examples/qml_features/rust/src/uncreatable.rs b/examples/qml_features/rust/src/uncreatable.rs index c907fa541..d826393b3 100644 --- a/examples/qml_features/rust/src/uncreatable.rs +++ b/examples/qml_features/rust/src/uncreatable.rs @@ -3,12 +3,17 @@ // // SPDX-License-Identifier: MIT OR Apache-2.0 +//! This example shows how a QML_UNCREATABLE can be used + +/// A CXX-Qt bridge which shows how a QML_UNCREATABLE can be used // ANCHOR: book_macro_code #[cxx_qt::bridge(cxx_file_stem = "rust_uncreatable")] pub mod ffi { + /// A QObject which is a QML_UNCREATABLE #[cxx_qt::qobject(qml_uri = "com.kdab.cxx_qt.demo", qml_version = "1.0", qml_uncreatable)] #[derive(Default)] pub struct RustUncreatable { + /// A value Q_PROPERTY #[qproperty] value: i32, } diff --git a/examples/qml_minimal/rust/src/cxxqt_object.rs b/examples/qml_minimal/rust/src/cxxqt_object.rs index 178ca9831..63adb34ee 100644 --- a/examples/qml_minimal/rust/src/cxxqt_object.rs +++ b/examples/qml_minimal/rust/src/cxxqt_object.rs @@ -8,17 +8,20 @@ // ANCHOR: book_cxx_qt_module // ANCHOR: book_bridge_macro +/// The bridge definition for our QObject #[cxx_qt::bridge] -mod my_object { +pub mod my_object { // ANCHOR_END: book_bridge_macro // ANCHOR: book_qstring_import unsafe extern "C++" { include!("cxx-qt-lib/qstring.h"); + /// An alias to the QString type type QString = cxx_qt_lib::QString; } // ANCHOR_END: book_qstring_import + /// The Rust struct for the QObject // ANCHOR: book_rustobj_struct #[cxx_qt::qobject(qml_uri = "com.kdab.cxx_qt.demo", qml_version = "1.0")] pub struct MyObject { @@ -42,12 +45,14 @@ mod my_object { // ANCHOR: book_rustobj_impl impl qobject::MyObject { + /// Increment the number Q_PROPERTY #[qinvokable] pub fn increment_number(self: Pin<&mut Self>) { let previous = *self.as_ref().number(); self.set_number(previous + 1); } + /// Print a log message with the given string and number #[qinvokable] pub fn say_hi(&self, string: &QString, number: i32) { println!("Hi from Rust! String is '{string}' and number is {number}"); From 04310bde9ffa69984c769559f5815da5be8621da Mon Sep 17 00:00:00 2001 From: Andrew Hayzen Date: Fri, 5 May 2023 16:35:44 +0100 Subject: [PATCH 4/7] docs: fix warnings from cargo doc --- crates/cxx-qt-build/src/lib.rs | 6 +++--- crates/cxx-qt-lib/src/core/qstringlist.rs | 4 ++-- examples/demo_threading/rust/src/lib.rs | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/crates/cxx-qt-build/src/lib.rs b/crates/cxx-qt-build/src/lib.rs index 21d82b629..eec03ddf3 100644 --- a/crates/cxx-qt-build/src/lib.rs +++ b/crates/cxx-qt-build/src/lib.rs @@ -233,12 +233,12 @@ fn generate_cxxqt_cpp_files( Ok(generated_file_paths) } -/// Run cxx-qt's C++ code generator on Rust modules marked with the [cxx_qt::bridge] macro, compile -/// the code, and link to Qt. This is the complement of the [cxx_qt::bridge] macro, which the Rust +/// Run cxx-qt's C++ code generator on Rust modules marked with the `cxx_qt::bridge` macro, compile +/// the code, and link to Qt. This is the complement of the `cxx_qt::bridge` macro, which the Rust /// compiler uses to generate the corresponding Rust code. No dependencies besides Qt, a C++17 compiler, /// and Rust toolchain are required. /// -/// For example, if your [cxx_qt::bridge] module is in a file called `src/lib.rs` within your crate, +/// For example, if your `cxx_qt::bridge` module is in a file called `src/lib.rs` within your crate, /// put this in your [build.rs](https://doc.rust-lang.org/cargo/reference/build-scripts.html): /// /// ```no_run diff --git a/crates/cxx-qt-lib/src/core/qstringlist.rs b/crates/cxx-qt-lib/src/core/qstringlist.rs index 1d7097457..0725dd3af 100644 --- a/crates/cxx-qt-lib/src/core/qstringlist.rs +++ b/crates/cxx-qt-lib/src/core/qstringlist.rs @@ -151,14 +151,14 @@ impl From<&QString> for QStringList { } impl From<&QList> for QStringList { - /// Converts a QList into QStringList. + /// Converts a `QList` into QStringList. fn from(list: &QList) -> Self { ffi::qstringlist_from_qlist_qstring(list) } } impl From<&QStringList> for QList { - /// Converts a QStringList into a QList + /// Converts a QStringList into a `QList` fn from(list: &QStringList) -> Self { ffi::qstringlist_as_qlist_qstring(list) } diff --git a/examples/demo_threading/rust/src/lib.rs b/examples/demo_threading/rust/src/lib.rs index 3bc9d32d7..9c0566cb1 100644 --- a/examples/demo_threading/rust/src/lib.rs +++ b/examples/demo_threading/rust/src/lib.rs @@ -48,7 +48,7 @@ mod ffi { /// This uses an Arc inside the Mutex as well as outside so that the HashMap is only /// cloned when required. By using Arc::make_mut on the inner HashMap data is only cloned /// when mutating if another thread is still holding onto reference to the data. - /// https://doc.rust-lang.org/std/sync/struct.Arc.html#method.make_mut + /// sensors_map: Arc>>, } From 1c99d101f8cb9f5a5cf612ebc2551dc0f8602b94 Mon Sep 17 00:00:00 2001 From: Andrew Hayzen Date: Fri, 5 May 2023 16:35:58 +0100 Subject: [PATCH 5/7] cmake: ensure that cargo doc is tested --- CMakeLists.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index e1429fa08..46c08a491 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -194,11 +194,12 @@ endif() # from the main build. set(CARGO_TARGET_DIR "${CMAKE_BINARY_DIR}/${BUILD_DIR}/cargo/build") -# Add CMake tests for `cargo test/clippy/fmt`. +# Add CMake tests for `cargo test/clippy/fmt/doc`. add_test(NAME cargo_tests COMMAND cargo test --all-targets --target-dir ${CARGO_TARGET_DIR}) add_test(NAME cargo_doc_tests COMMAND cargo test --doc --target-dir ${CARGO_TARGET_DIR}) +add_test(NAME cargo_doc COMMAND cargo doc --workspace --target-dir ${CARGO_TARGET_DIR}) add_test(NAME cargo_clippy COMMAND cargo clippy --all-targets --target-dir ${CARGO_TARGET_DIR} -- -D warnings) add_test(NAME cargo_fmt COMMAND cargo fmt --all --check WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}) @@ -206,6 +207,9 @@ add_test(NAME cargo_fmt COMMAND cargo fmt --all --check WORKING_DIRECTORY ${CMAK set_tests_properties(cargo_tests cargo_doc_tests cargo_clippy cargo_fmt PROPERTIES ENVIRONMENT_MODIFICATION "${CARGO_ENV}" ) +set_tests_properties(cargo_doc PROPERTIES + ENVIRONMENT_MODIFICATION "${CARGO_ENV};RUSTDOCFLAGS=set:--deny=warnings" +) # Ensure test inputs and outputs are formatted file(GLOB CXX_QT_GEN_TEST_INPUTS ${CMAKE_CURRENT_SOURCE_DIR}/crates/cxx-qt-gen/test_inputs/*.rs) From a9af2e712fb574989aa577d8fbb0ec4f2aa180c4 Mon Sep 17 00:00:00 2001 From: Andrew Hayzen Date: Mon, 15 May 2023 17:05:38 +0100 Subject: [PATCH 6/7] cxx-qt-gen: copy mod visibility for re-exports --- crates/cxx-qt-gen/src/writer/rust/mod.rs | 9 ++++++--- crates/cxx-qt-gen/test_outputs/inheritance.rs | 2 +- crates/cxx-qt-gen/test_outputs/invokables.rs | 2 +- crates/cxx-qt-gen/test_outputs/properties.rs | 2 +- crates/cxx-qt-gen/test_outputs/signals.rs | 2 +- 5 files changed, 10 insertions(+), 7 deletions(-) diff --git a/crates/cxx-qt-gen/src/writer/rust/mod.rs b/crates/cxx-qt-gen/src/writer/rust/mod.rs index 5a4c1ca52..94c57e024 100644 --- a/crates/cxx-qt-gen/src/writer/rust/mod.rs +++ b/crates/cxx-qt-gen/src/writer/rust/mod.rs @@ -224,11 +224,14 @@ pub fn write_rust(generated: &GeneratedRustBlocks) -> TokenStream { cxx_mod.content = Some((syn::token::Brace::default(), cxx_mod_contents)); } + // Copy the visiblity of the module so we re-export things in the same way + let cxx_mod_visiblity = &generated.cxx_mod.vis; + quote! { #[cxx::bridge(namespace = #namespace)] #cxx_mod - pub use self::#cxx_qt_mod_ident::*; + #cxx_mod_visiblity use self::#cxx_qt_mod_ident::*; mod #cxx_qt_mod_ident { use super::#cxx_mod_ident::*; use std::pin::Pin; @@ -476,7 +479,7 @@ mod tests { } } - pub use self::cxx_qt_ffi::*; + use self::cxx_qt_ffi::*; mod cxx_qt_ffi { use super::ffi::*; use std::pin::Pin; @@ -683,7 +686,7 @@ mod tests { } } - pub use self::cxx_qt_ffi::*; + use self::cxx_qt_ffi::*; mod cxx_qt_ffi { use super::ffi::*; use std::pin::Pin; diff --git a/crates/cxx-qt-gen/test_outputs/inheritance.rs b/crates/cxx-qt-gen/test_outputs/inheritance.rs index 88c7edb68..88cff0bed 100644 --- a/crates/cxx-qt-gen/test_outputs/inheritance.rs +++ b/crates/cxx-qt-gen/test_outputs/inheritance.rs @@ -102,7 +102,7 @@ mod inheritance { fn create_rs_my_object() -> Box; } } -pub use self::cxx_qt_inheritance::*; +use self::cxx_qt_inheritance::*; mod cxx_qt_inheritance { use super::inheritance::*; use std::pin::Pin; diff --git a/crates/cxx-qt-gen/test_outputs/invokables.rs b/crates/cxx-qt-gen/test_outputs/invokables.rs index ac0c421b0..d60510284 100644 --- a/crates/cxx-qt-gen/test_outputs/invokables.rs +++ b/crates/cxx-qt-gen/test_outputs/invokables.rs @@ -140,7 +140,7 @@ mod ffi { } } -pub use self::cxx_qt_ffi::*; +use self::cxx_qt_ffi::*; mod cxx_qt_ffi { use super::ffi::*; use std::pin::Pin; diff --git a/crates/cxx-qt-gen/test_outputs/properties.rs b/crates/cxx-qt-gen/test_outputs/properties.rs index 93bacafba..f46f3b317 100644 --- a/crates/cxx-qt-gen/test_outputs/properties.rs +++ b/crates/cxx-qt-gen/test_outputs/properties.rs @@ -149,7 +149,7 @@ mod ffi { } } -pub use self::cxx_qt_ffi::*; +use self::cxx_qt_ffi::*; mod cxx_qt_ffi { use super::ffi::*; use std::pin::Pin; diff --git a/crates/cxx-qt-gen/test_outputs/signals.rs b/crates/cxx-qt-gen/test_outputs/signals.rs index 125bd5d29..262e51a75 100644 --- a/crates/cxx-qt-gen/test_outputs/signals.rs +++ b/crates/cxx-qt-gen/test_outputs/signals.rs @@ -121,7 +121,7 @@ mod ffi { } } -pub use self::cxx_qt_ffi::*; +use self::cxx_qt_ffi::*; mod cxx_qt_ffi { use super::ffi::*; use std::pin::Pin; From 42ec8f37ce9e6e5db90821f2fe6df7cdbc0061ec Mon Sep 17 00:00:00 2001 From: Andrew Hayzen Date: Wed, 17 May 2023 15:05:20 +0100 Subject: [PATCH 7/7] docs: various typos and fixes to doc lines --- .../cxx-qt-gen/src/generator/rust/qobject.rs | 4 +-- crates/cxx-qt-gen/src/writer/rust/mod.rs | 34 +++++++++++-------- crates/cxx-qt-gen/test_outputs/inheritance.rs | 11 +++--- crates/cxx-qt-gen/test_outputs/invokables.rs | 11 +++--- .../test_outputs/passthrough_and_naming.rs | 20 ++++++----- crates/cxx-qt-gen/test_outputs/properties.rs | 11 +++--- crates/cxx-qt-gen/test_outputs/signals.rs | 11 +++--- examples/qml_features/rust/src/containers.rs | 8 ++--- .../rust/src/custom_base_class.rs | 4 +-- examples/qml_features/rust/src/lib.rs | 2 +- .../qml_features/rust/src/nested_qobjects.rs | 6 ++-- .../qml_features/rust/src/serialisation.rs | 2 +- examples/qml_features/rust/src/threading.rs | 2 +- examples/qml_features/rust/src/types.rs | 2 +- examples/qml_features/rust/src/uncreatable.rs | 4 +-- 15 files changed, 71 insertions(+), 61 deletions(-) diff --git a/crates/cxx-qt-gen/src/generator/rust/qobject.rs b/crates/cxx-qt-gen/src/generator/rust/qobject.rs index 63025f5c9..0ebaf417d 100644 --- a/crates/cxx-qt-gen/src/generator/rust/qobject.rs +++ b/crates/cxx-qt-gen/src/generator/rust/qobject.rs @@ -165,7 +165,7 @@ fn generate_qobject_definitions( #[doc = "The C++ type for the QObject "] #[doc = #rust_struct_name_rust_str] #[doc = "\n"] - #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "Use this type when referring to the QObject as a pointer"] #[doc = "\n"] #[doc = "See the book for more information: "] #[cxx_name = #cpp_class_name_cpp] @@ -264,7 +264,7 @@ mod tests { #[doc = "The C++ type for the QObject "] #[doc = "MyObject"] #[doc = "\n"] - #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "Use this type when referring to the QObject as a pointer"] #[doc = "\n"] #[doc = "See the book for more information: "] #[cxx_name = "MyObject"] diff --git a/crates/cxx-qt-gen/src/writer/rust/mod.rs b/crates/cxx-qt-gen/src/writer/rust/mod.rs index 94c57e024..be36acb14 100644 --- a/crates/cxx-qt-gen/src/writer/rust/mod.rs +++ b/crates/cxx-qt-gen/src/writer/rust/mod.rs @@ -38,7 +38,7 @@ fn cxx_bridge_common_blocks(qobject: &GeneratedRustQObject) -> Vec /// CXX doesn't support having generic types in the function yet /// so we cannot have CxxQtThread in cxx-qt-lib and then use that here /// For now we use a type alias in C++ then use it like a normal type here - /// https://github.com/dtolnay/cxx/issues/683 + /// type #cxx_qt_thread_ident; /// Retrieve an immutable reference to the Rust struct backing this C++ object @@ -74,7 +74,8 @@ fn cxx_bridge_common_blocks(qobject: &GeneratedRustQObject) -> Vec extern "C++" { /// Retrieve a mutable reference to the Rust struct backing this C++ object /// - /// This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually. + /// This method is unsafe because it allows a Q_PROPERTY to be modified without emitting its changed signal. + /// The property changed signal must be emitted manually. #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut #cpp_struct_ident>) -> Pin<&mut #rust_struct_ident>; } @@ -199,7 +200,7 @@ pub fn write_rust(generated: &GeneratedRustBlocks) -> TokenStream { #[doc = "The C++ type for the QObject "] #[doc = #rust_struct_ident_str] #[doc = "\n"] - #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "Use this type when referring to the QObject as a pointer"] #[doc = "\n"] #[doc = "See the book for more information: "] pub type #rust_struct_ident = super::#cpp_struct_ident; @@ -209,7 +210,7 @@ pub fn write_rust(generated: &GeneratedRustBlocks) -> TokenStream { // Create the qobject block for the type alias cxx_qt_mod_contents.push( syn::parse2(quote! { - /// Generated CXX-Qt module containing type alias to the C++ type of the QObjects + /// Generated CXX-Qt module containing type alias to the C++ types of the QObjects pub mod qobject { #(#qobject_types)* } @@ -432,7 +433,7 @@ mod tests { /// CXX doesn't support having generic types in the function yet /// so we cannot have CxxQtThread in cxx-qt-lib and then use that here /// For now we use a type alias in C++ then use it like a normal type here - /// https://github.com/dtolnay/cxx/issues/683 + /// type MyObjectCxxQtThread; /// Retrieve an immutable reference to the Rust struct backing this C++ object @@ -464,7 +465,8 @@ mod tests { extern "C++" { /// Retrieve a mutable reference to the Rust struct backing this C++ object /// - /// This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually. + /// This method is unsafe because it allows a Q_PROPERTY to be modified without emitting its changed signal. + /// The property changed signal must be emitted manually. #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut MyObjectQt>) -> Pin<&mut MyObject>; } @@ -530,12 +532,12 @@ mod tests { std::default::Default::default() } - /// Generated CXX-Qt module containing type alias to the C++ type of the QObjects + /// Generated CXX-Qt module containing type alias to the C++ types of the QObjects pub mod qobject { #[doc = "The C++ type for the QObject "] #[doc = "MyObject"] #[doc = "\n"] - #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "Use this type when referring to the QObject as a pointer"] #[doc = "\n"] #[doc = "See the book for more information: "] pub type MyObject = super::MyObjectQt; @@ -578,7 +580,7 @@ mod tests { /// CXX doesn't support having generic types in the function yet /// so we cannot have CxxQtThread in cxx-qt-lib and then use that here /// For now we use a type alias in C++ then use it like a normal type here - /// https://github.com/dtolnay/cxx/issues/683 + /// type FirstObjectCxxQtThread; /// Retrieve an immutable reference to the Rust struct backing this C++ object @@ -610,7 +612,8 @@ mod tests { extern "C++" { /// Retrieve a mutable reference to the Rust struct backing this C++ object /// - /// This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually. + /// This method is unsafe because it allows a Q_PROPERTY to be modified without emitting its changed signal. + /// The property changed signal must be emitted manually. #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut FirstObjectQt>) -> Pin<&mut FirstObject>; } @@ -639,7 +642,7 @@ mod tests { /// CXX doesn't support having generic types in the function yet /// so we cannot have CxxQtThread in cxx-qt-lib and then use that here /// For now we use a type alias in C++ then use it like a normal type here - /// https://github.com/dtolnay/cxx/issues/683 + /// type SecondObjectCxxQtThread; /// Retrieve an immutable reference to the Rust struct backing this C++ object @@ -671,7 +674,8 @@ mod tests { extern "C++" { /// Retrieve a mutable reference to the Rust struct backing this C++ object /// - /// This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually. + /// This method is unsafe because it allows a Q_PROPERTY to be modified without emitting its changed signal. + /// The property changed signal must be emitted manually. #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut SecondObjectQt>) -> Pin<&mut SecondObject>; } @@ -778,19 +782,19 @@ mod tests { std::default::Default::default() } - /// Generated CXX-Qt module containing type alias to the C++ type of the QObjects + /// Generated CXX-Qt module containing type alias to the C++ types of the QObjects pub mod qobject { #[doc = "The C++ type for the QObject "] #[doc = "FirstObject"] #[doc = "\n"] - #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "Use this type when referring to the QObject as a pointer"] #[doc = "\n"] #[doc = "See the book for more information: "] pub type FirstObject = super::FirstObjectQt; #[doc = "The C++ type for the QObject "] #[doc = "SecondObject"] #[doc = "\n"] - #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "Use this type when referring to the QObject as a pointer"] #[doc = "\n"] #[doc = "See the book for more information: "] pub type SecondObject = super::SecondObjectQt; diff --git a/crates/cxx-qt-gen/test_outputs/inheritance.rs b/crates/cxx-qt-gen/test_outputs/inheritance.rs index 88cff0bed..8b2be26c0 100644 --- a/crates/cxx-qt-gen/test_outputs/inheritance.rs +++ b/crates/cxx-qt-gen/test_outputs/inheritance.rs @@ -19,7 +19,7 @@ mod inheritance { #[doc = "The C++ type for the QObject "] #[doc = "MyObject"] #[doc = "\n"] - #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "Use this type when referring to the QObject as a pointer"] #[doc = "\n"] #[doc = "See the book for more information: "] #[cxx_name = "MyObject"] @@ -63,7 +63,7 @@ mod inheritance { #[doc = r" CXX doesn't support having generic types in the function yet"] #[doc = r" so we cannot have CxxQtThread in cxx-qt-lib and then use that here"] #[doc = r" For now we use a type alias in C++ then use it like a normal type here"] - #[doc = r" https://github.com/dtolnay/cxx/issues/683"] + #[doc = r" "] type MyObjectCxxQtThread; #[doc = r" Retrieve an immutable reference to the Rust struct backing this C++ object"] #[cxx_name = "unsafeRust"] @@ -90,7 +90,8 @@ mod inheritance { extern "C++" { #[doc = r" Retrieve a mutable reference to the Rust struct backing this C++ object"] #[doc = r""] - #[doc = r" This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually."] + #[doc = r" This method is unsafe because it allows a Q_PROPERTY to be modified without emitting its changed signal."] + #[doc = r" The property changed signal must be emitted manually."] #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut MyObjectQt>) -> Pin<&mut MyObject>; } @@ -190,12 +191,12 @@ mod cxx_qt_inheritance { pub fn create_rs_my_object() -> std::boxed::Box { std::default::Default::default() } - #[doc = r" Generated CXX-Qt module containing type alias to the C++ type of the QObjects"] + #[doc = r" Generated CXX-Qt module containing type alias to the C++ types of the QObjects"] pub mod qobject { #[doc = "The C++ type for the QObject "] #[doc = "MyObject"] #[doc = "\n"] - #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "Use this type when referring to the QObject as a pointer"] #[doc = "\n"] #[doc = "See the book for more information: "] pub type MyObject = super::MyObjectQt; diff --git a/crates/cxx-qt-gen/test_outputs/invokables.rs b/crates/cxx-qt-gen/test_outputs/invokables.rs index d60510284..361fd7ee3 100644 --- a/crates/cxx-qt-gen/test_outputs/invokables.rs +++ b/crates/cxx-qt-gen/test_outputs/invokables.rs @@ -23,7 +23,7 @@ mod ffi { #[doc = "The C++ type for the QObject "] #[doc = "MyObject"] #[doc = "\n"] - #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "Use this type when referring to the QObject as a pointer"] #[doc = "\n"] #[doc = "See the book for more information: "] #[cxx_name = "MyObject"] @@ -93,7 +93,7 @@ mod ffi { #[doc = r" CXX doesn't support having generic types in the function yet"] #[doc = r" so we cannot have CxxQtThread in cxx-qt-lib and then use that here"] #[doc = r" For now we use a type alias in C++ then use it like a normal type here"] - #[doc = r" https://github.com/dtolnay/cxx/issues/683"] + #[doc = r" "] type MyObjectCxxQtThread; #[doc = r" Retrieve an immutable reference to the Rust struct backing this C++ object"] @@ -125,7 +125,8 @@ mod ffi { extern "C++" { #[doc = r" Retrieve a mutable reference to the Rust struct backing this C++ object"] #[doc = r""] - #[doc = r" This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually."] + #[doc = r" This method is unsafe because it allows a Q_PROPERTY to be modified without emitting its changed signal."] + #[doc = r" The property changed signal must be emitted manually."] #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut MyObjectQt>) -> Pin<&mut MyObject>; } @@ -330,12 +331,12 @@ mod cxx_qt_ffi { std::default::Default::default() } - #[doc = r" Generated CXX-Qt module containing type alias to the C++ type of the QObjects"] + #[doc = r" Generated CXX-Qt module containing type alias to the C++ types of the QObjects"] pub mod qobject { #[doc = "The C++ type for the QObject "] #[doc = "MyObject"] #[doc = "\n"] - #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "Use this type when referring to the QObject as a pointer"] #[doc = "\n"] #[doc = "See the book for more information: "] pub type MyObject = super::MyObjectQt; diff --git a/crates/cxx-qt-gen/test_outputs/passthrough_and_naming.rs b/crates/cxx-qt-gen/test_outputs/passthrough_and_naming.rs index 7ba888c4e..1f3228abd 100644 --- a/crates/cxx-qt-gen/test_outputs/passthrough_and_naming.rs +++ b/crates/cxx-qt-gen/test_outputs/passthrough_and_naming.rs @@ -78,7 +78,7 @@ pub mod ffi { #[doc = "The C++ type for the QObject "] #[doc = "MyObject"] #[doc = "\n"] - #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "Use this type when referring to the QObject as a pointer"] #[doc = "\n"] #[doc = "See the book for more information: "] #[cxx_name = "MyObject"] @@ -128,7 +128,7 @@ pub mod ffi { #[doc = r" CXX doesn't support having generic types in the function yet"] #[doc = r" so we cannot have CxxQtThread in cxx-qt-lib and then use that here"] #[doc = r" For now we use a type alias in C++ then use it like a normal type here"] - #[doc = r" https://github.com/dtolnay/cxx/issues/683"] + #[doc = r" "] type MyObjectCxxQtThread; #[doc = r" Retrieve an immutable reference to the Rust struct backing this C++ object"] @@ -160,7 +160,8 @@ pub mod ffi { extern "C++" { #[doc = r" Retrieve a mutable reference to the Rust struct backing this C++ object"] #[doc = r""] - #[doc = r" This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually."] + #[doc = r" This method is unsafe because it allows a Q_PROPERTY to be modified without emitting its changed signal."] + #[doc = r" The property changed signal must be emitted manually."] #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut MyObjectQt>) -> Pin<&mut MyObject>; } @@ -178,7 +179,7 @@ pub mod ffi { #[doc = "The C++ type for the QObject "] #[doc = "SecondObject"] #[doc = "\n"] - #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "Use this type when referring to the QObject as a pointer"] #[doc = "\n"] #[doc = "See the book for more information: "] #[cxx_name = "SecondObject"] @@ -228,7 +229,7 @@ pub mod ffi { #[doc = r" CXX doesn't support having generic types in the function yet"] #[doc = r" so we cannot have CxxQtThread in cxx-qt-lib and then use that here"] #[doc = r" For now we use a type alias in C++ then use it like a normal type here"] - #[doc = r" https://github.com/dtolnay/cxx/issues/683"] + #[doc = r" "] type SecondObjectCxxQtThread; #[doc = r" Retrieve an immutable reference to the Rust struct backing this C++ object"] #[cxx_name = "unsafeRust"] @@ -256,7 +257,8 @@ pub mod ffi { extern "C++" { #[doc = r" Retrieve a mutable reference to the Rust struct backing this C++ object"] #[doc = r""] - #[doc = r" This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually."] + #[doc = r" This method is unsafe because it allows a Q_PROPERTY to be modified without emitting its changed signal."] + #[doc = r" The property changed signal must be emitted manually."] #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut SecondObjectQt>) -> Pin<&mut SecondObject>; } @@ -553,19 +555,19 @@ mod cxx_qt_ffi { std::default::Default::default() } - #[doc = r" Generated CXX-Qt module containing type alias to the C++ type of the QObjects"] + #[doc = r" Generated CXX-Qt module containing type alias to the C++ types of the QObjects"] pub mod qobject { #[doc = "The C++ type for the QObject "] #[doc = "MyObject"] #[doc = "\n"] - #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "Use this type when referring to the QObject as a pointer"] #[doc = "\n"] #[doc = "See the book for more information: "] pub type MyObject = super::MyObjectQt; #[doc = "The C++ type for the QObject "] #[doc = "SecondObject"] #[doc = "\n"] - #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "Use this type when referring to the QObject as a pointer"] #[doc = "\n"] #[doc = "See the book for more information: "] pub type SecondObject = super::SecondObjectQt; diff --git a/crates/cxx-qt-gen/test_outputs/properties.rs b/crates/cxx-qt-gen/test_outputs/properties.rs index f46f3b317..ab4c63e22 100644 --- a/crates/cxx-qt-gen/test_outputs/properties.rs +++ b/crates/cxx-qt-gen/test_outputs/properties.rs @@ -21,7 +21,7 @@ mod ffi { #[doc = "The C++ type for the QObject "] #[doc = "MyObject"] #[doc = "\n"] - #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "Use this type when referring to the QObject as a pointer"] #[doc = "\n"] #[doc = "See the book for more information: "] #[cxx_name = "MyObject"] @@ -102,7 +102,7 @@ mod ffi { #[doc = r" CXX doesn't support having generic types in the function yet"] #[doc = r" so we cannot have CxxQtThread in cxx-qt-lib and then use that here"] #[doc = r" For now we use a type alias in C++ then use it like a normal type here"] - #[doc = r" https://github.com/dtolnay/cxx/issues/683"] + #[doc = r" "] type MyObjectCxxQtThread; #[doc = r" Retrieve an immutable reference to the Rust struct backing this C++ object"] @@ -134,7 +134,8 @@ mod ffi { extern "C++" { #[doc = r" Retrieve a mutable reference to the Rust struct backing this C++ object"] #[doc = r""] - #[doc = r" This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually."] + #[doc = r" This method is unsafe because it allows a Q_PROPERTY to be modified without emitting its changed signal."] + #[doc = r" The property changed signal must be emitted manually."] #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut MyObjectQt>) -> Pin<&mut MyObject>; } @@ -387,12 +388,12 @@ mod cxx_qt_ffi { std::default::Default::default() } - #[doc = r" Generated CXX-Qt module containing type alias to the C++ type of the QObjects"] + #[doc = r" Generated CXX-Qt module containing type alias to the C++ types of the QObjects"] pub mod qobject { #[doc = "The C++ type for the QObject "] #[doc = "MyObject"] #[doc = "\n"] - #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "Use this type when referring to the QObject as a pointer"] #[doc = "\n"] #[doc = "See the book for more information: "] pub type MyObject = super::MyObjectQt; diff --git a/crates/cxx-qt-gen/test_outputs/signals.rs b/crates/cxx-qt-gen/test_outputs/signals.rs index 262e51a75..547000d7f 100644 --- a/crates/cxx-qt-gen/test_outputs/signals.rs +++ b/crates/cxx-qt-gen/test_outputs/signals.rs @@ -21,7 +21,7 @@ mod ffi { #[doc = "The C++ type for the QObject "] #[doc = "MyObject"] #[doc = "\n"] - #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "Use this type when referring to the QObject as a pointer"] #[doc = "\n"] #[doc = "See the book for more information: "] #[cxx_name = "MyObject"] @@ -74,7 +74,7 @@ mod ffi { #[doc = r" CXX doesn't support having generic types in the function yet"] #[doc = r" so we cannot have CxxQtThread in cxx-qt-lib and then use that here"] #[doc = r" For now we use a type alias in C++ then use it like a normal type here"] - #[doc = r" https://github.com/dtolnay/cxx/issues/683"] + #[doc = r" "] type MyObjectCxxQtThread; #[doc = r" Retrieve an immutable reference to the Rust struct backing this C++ object"] @@ -106,7 +106,8 @@ mod ffi { extern "C++" { #[doc = r" Retrieve a mutable reference to the Rust struct backing this C++ object"] #[doc = r""] - #[doc = r" This method is unsafe as if a Q_PROPERTY is modified its changed signal must be triggered manually."] + #[doc = r" This method is unsafe because it allows a Q_PROPERTY to be modified without emitting its changed signal."] + #[doc = r" The property changed signal must be emitted manually."] #[cxx_name = "unsafeRustMut"] unsafe fn rust_mut(self: Pin<&mut MyObjectQt>) -> Pin<&mut MyObject>; } @@ -224,12 +225,12 @@ mod cxx_qt_ffi { std::default::Default::default() } - #[doc = r" Generated CXX-Qt module containing type alias to the C++ type of the QObjects"] + #[doc = r" Generated CXX-Qt module containing type alias to the C++ types of the QObjects"] pub mod qobject { #[doc = "The C++ type for the QObject "] #[doc = "MyObject"] #[doc = "\n"] - #[doc = "Use type when referring to the QObject as a pointer"] + #[doc = "Use this type when referring to the QObject as a pointer"] #[doc = "\n"] #[doc = "See the book for more information: "] pub type MyObject = super::MyObjectQt; diff --git a/examples/qml_features/rust/src/containers.rs b/examples/qml_features/rust/src/containers.rs index 51dd23f28..2fb261787 100644 --- a/examples/qml_features/rust/src/containers.rs +++ b/examples/qml_features/rust/src/containers.rs @@ -3,9 +3,9 @@ // // SPDX-License-Identifier: MIT OR Apache-2.0 -//! This example shows how container types can be used +//! This example shows how Qt container types can be used -/// A CXX-Qt bridge which shows container types can be used +/// A CXX-Qt bridge which shows how to use Qt container types #[cxx_qt::bridge(cxx_file_stem = "rust_containers")] pub mod ffi { unsafe extern "C++" { @@ -34,7 +34,7 @@ pub mod ffi { /// A QObject which stores container types internally /// - /// Then it has Q_PROPERTYs which expose a string of the container to be show in QML + /// It has Q_PROPERTYs which expose a string with the container's contents to show in QML #[cxx_qt::qobject(qml_uri = "com.kdab.cxx_qt.demo", qml_version = "1.0")] #[derive(Default)] pub struct RustContainers { @@ -57,7 +57,7 @@ pub mod ffi { } impl qobject::RustContainers { - /// Reset all the container types + /// Reset all the containers #[qinvokable] pub fn reset(mut self: Pin<&mut Self>) { self.as_mut().set_hash(QHash_QString_QVariant::default()); diff --git a/examples/qml_features/rust/src/custom_base_class.rs b/examples/qml_features/rust/src/custom_base_class.rs index f4632cad1..a72064d22 100644 --- a/examples/qml_features/rust/src/custom_base_class.rs +++ b/examples/qml_features/rust/src/custom_base_class.rs @@ -31,7 +31,7 @@ pub mod ffi { type QVector_i32 = cxx_qt_lib::QVector; } - /// A struct which will derive from a QAbstractListModel + /// A struct which inherits from QAbstractListModel // ANCHOR: book_inherit_qalm // ANCHOR: book_qobject_base #[cxx_qt::qobject( @@ -71,7 +71,7 @@ pub mod ffi { self.add_cpp_context(); } - /// On a background thread add a given number of rows to the QAbstractListModel + /// On a background thread, add a given number of rows to the QAbstractListModel #[qinvokable] pub fn add_on_thread(self: Pin<&mut Self>, mut counter: i32) { let qt_thread = self.qt_thread(); diff --git a/examples/qml_features/rust/src/lib.rs b/examples/qml_features/rust/src/lib.rs index 912f55de8..ae54ad867 100644 --- a/examples/qml_features/rust/src/lib.rs +++ b/examples/qml_features/rust/src/lib.rs @@ -7,7 +7,7 @@ // Use this crate to test that missing_docs works with our generated code #![deny(missing_docs)] -//! This example provides demostrations of most of the features of CXX-Qt +//! This example provides demonstrations of most of the features of CXX-Qt //! split into separate modules pub mod containers; diff --git a/examples/qml_features/rust/src/nested_qobjects.rs b/examples/qml_features/rust/src/nested_qobjects.rs index f1e77ec67..412d02ef8 100644 --- a/examples/qml_features/rust/src/nested_qobjects.rs +++ b/examples/qml_features/rust/src/nested_qobjects.rs @@ -12,7 +12,7 @@ pub mod ffi { // ANCHOR: book_extern_block unsafe extern "C++" { #[cxx_name = "InnerObject"] - /// THe C++ part of the InnerObject so that it can be referred to + /// The C++ part of the InnerObject so that it can be referred to type CxxInnerObject = super::qobject::InnerObject; } // ANCHOR_END: book_extern_block @@ -25,7 +25,7 @@ pub mod ffi { counter: i32, } - /// The outer QObject which has a Q_PROPERTY to the inner QObject + /// The outer QObject which has a Q_PROPERTY pointing to the inner QObject #[cxx_qt::qobject(qml_uri = "com.kdab.cxx_qt.demo", qml_version = "1.0")] pub struct OuterObject { #[qproperty] @@ -64,7 +64,7 @@ pub mod ffi { self.emit(OuterSignals::Called { inner }); } - /// Reset the cont of the inner QObject stored in the Q_PROPERTY + /// Reset the counter of the inner QObject stored in the Q_PROPERTY #[qinvokable] pub fn reset(self: Pin<&mut Self>) { // We need to convert the *mut T to a Pin<&mut T> so that we can reach the methods diff --git a/examples/qml_features/rust/src/serialisation.rs b/examples/qml_features/rust/src/serialisation.rs index d7639fee9..107d3dbc6 100644 --- a/examples/qml_features/rust/src/serialisation.rs +++ b/examples/qml_features/rust/src/serialisation.rs @@ -26,7 +26,7 @@ impl From<&Serialisation> for DataSerde { } } -/// A CXX-Qt bridge which shows how a serialisation can be used +/// A CXX-Qt bridge which shows how use serde for (de)serialization of the data in a QObjects' QPROPERTY's #[cxx_qt::bridge(cxx_file_stem = "serialisation")] pub mod ffi { use super::DataSerde; diff --git a/examples/qml_features/rust/src/threading.rs b/examples/qml_features/rust/src/threading.rs index 13aa9a8de..d6f7efe09 100644 --- a/examples/qml_features/rust/src/threading.rs +++ b/examples/qml_features/rust/src/threading.rs @@ -5,7 +5,7 @@ //! This example shows how a threading can be used -/// A CXX-Qt bridge which shows how a threading can be used +/// This example shows how to send data from a background thread to the Qt event loop to update data in the QObject // ANCHOR: book_macro_code // ANCHOR: book_namespace_macro #[cxx_qt::bridge(cxx_file_stem = "threading_website", namespace = "cxx_qt::website")] diff --git a/examples/qml_features/rust/src/types.rs b/examples/qml_features/rust/src/types.rs index c05e32a75..9ab4eb222 100644 --- a/examples/qml_features/rust/src/types.rs +++ b/examples/qml_features/rust/src/types.rs @@ -55,7 +55,7 @@ pub mod ffi { /// CustomStruct which is a custom C++ type type CustomStruct = super::CustomStruct; - /// Return if the given QVariant can be converted into a CustomStruct + /// Return whether the given QVariant can be converted into a CustomStruct #[rust_name = "qvariant_can_convert_custom_type"] fn qvariantCanConvertCustomStruct(variant: &QVariant) -> bool; } diff --git a/examples/qml_features/rust/src/uncreatable.rs b/examples/qml_features/rust/src/uncreatable.rs index d826393b3..4908e3eee 100644 --- a/examples/qml_features/rust/src/uncreatable.rs +++ b/examples/qml_features/rust/src/uncreatable.rs @@ -3,9 +3,9 @@ // // SPDX-License-Identifier: MIT OR Apache-2.0 -//! This example shows how a QML_UNCREATABLE can be used +//! This example shows how a QML_UNCREATABLE QObject can be used -/// A CXX-Qt bridge which shows how a QML_UNCREATABLE can be used +/// A CXX-Qt bridge which shows how a QML_UNCREATABLE QObject can be used // ANCHOR: book_macro_code #[cxx_qt::bridge(cxx_file_stem = "rust_uncreatable")] pub mod ffi {