Improve docs

Author: BenFordTytherington

crates/cxx-qt/src/lib.rs

@@ -217,6 +217,8 @@ pub trait Threading: Sized {
 }
 
 #[doc(hidden)]
+// This is implemented when using `impl cxx_qt::Constructor<...> for ... {}` and allows Constructor to be implemented.
+// This is done with a trait bound on `Constructor` which avoids declaring constructors outside the bridge which aren't actually used.
 pub trait ConstructorDeclared<Arguments> {}
 
 /// This trait can be implemented on any [CxxQtType] to define a
@@ -226,10 +228,13 @@ pub trait ConstructorDeclared<Arguments> {}
 ///
 /// If this trait is implemented for a given [CxxQtType], it must also be declared inside the
 /// [cxx_qt::bridge](bridge) macro.
+/// Under the hood, this works by implementing a shim trait called [ConstructorDeclared].
+/// If this is not present, you cannot use your constructor, so if you encounter an error regarding this trait,
+/// it is most likely you have forgotten to declare your constructor inside the bridge.
 /// See the example below.
 ///
 /// Note that declaring an implementation of this trait will stop CXX-Qt from generating a default constructor.
-/// Therefore an implementation of [Default] is no longer required for the Rust type.
+/// Therefore, an implementation of [Default] is no longer required for the Rust type.
 ///
 /// # Minimal Example
 ///
@@ -241,7 +246,9 @@ pub trait ConstructorDeclared<Arguments> {}
 ///         type MyStruct = super::MyStructRust;
 ///     }
 ///
-///     // Declare that we want to use a custom constructor
+///     // Declare that we want to use a custom constructor,
+///     // which will implement `ConstructorDeclared` for these particular args.
+///     //
 ///     // Note that the arguments must be a tuple of CXX types.
 ///     // Any associated types that aren't included here are assumed to be `()`.
 ///     impl cxx_qt::Constructor<(i32, String), NewArguments=(i32, String)> for MyStruct {}
@@ -253,6 +260,7 @@ pub trait ConstructorDeclared<Arguments> {}
 ///     pub string: String
 /// }
 ///
+/// // After declaring we want a custom constructor in the bridge, we must implement it.
 /// impl cxx_qt::Constructor<(i32, String)> for qobject::MyStruct {
 ///     type BaseArguments = (); // Will be passed to the base class constructor
 ///     type InitializeArguments = (); // Will be passed to the "initialize" function