cxx-qt: activate doctests for the macros and deny missing docs in the crate

Related to #21

Author: ahayzen-kdab

crates/cxx-qt/Cargo.toml

@@ -23,3 +23,7 @@ proc-macro = true
 cxx-qt-gen.workspace = true
 proc-macro2.workspace = true
 syn.workspace = true
+
+[dev-dependencies]
+cxx.workspace = true
+cxx-qt-lib.workspace = true

crates/cxx-qt/src/lib.rs

@@ -3,6 +3,11 @@
 // SPDX-FileContributor: Gerhard de Clercq <[email protected]>
 //
 // SPDX-License-Identifier: MIT OR Apache-2.0
+
+#![deny(missing_docs)]
+
+//! The cxx-qt crate provides the procedural attribute macros which are used with cxx-qt.
+
 use proc_macro::TokenStream;
 use syn::{parse_macro_input, ItemMod};
 
@@ -12,23 +17,24 @@ use cxx_qt_gen::{write_rust, GeneratedRustBlocks, Parser};
 ///
 /// # Example
 ///
-/// ```ignore
+/// ```rust
 /// #[cxx_qt::bridge(namespace = "cxx_qt::my_object")]
 /// mod my_object {
 ///     #[cxx_qt::qobject]
 ///     #[derive(Default)]
-///     struct RustObj {
-///         #[qproperty]
-///         property: i32,
-///     }
+///     # // Note that we can't use properties as this confuses the linker on Windows
+///     pub struct MyObject;
 ///
-///     impl qobject::RustObj {
+///     impl qobject::MyObject {
 ///         #[qinvokable]
 ///         fn invokable(&self, a: i32, b: i32) -> i32 {
 ///             a + b
 ///         }
 ///     }
 /// }
+///
+/// # // Note that we need a fake main for doc tests to build
+/// # fn main() {}
 /// ```
 #[proc_macro_attribute]
 pub fn bridge(args: TokenStream, input: TokenStream) -> TokenStream {
@@ -58,14 +64,22 @@ pub fn bridge(args: TokenStream, input: TokenStream) -> TokenStream {
 ///
 /// # Example
 ///
-/// ```ignore
-/// #[cxx_qt::bridge(namespace = "cxx_qt::my_object")]
+/// ```rust
+/// #[cxx_qt::bridge]
 /// mod my_object {
+///     #[cxx_qt::qobject]
+///     #[derive(Default)]
+///     # // Note that we can't use properties as this confuses the linker on Windows
+///     pub struct MyObject;
+///
 ///     #[cxx_qt::qsignals(MyObject)]
-///     enum MySignals {
+///     pub enum MySignals {
 ///         Ready,
 ///     }
 /// }
+///
+/// # // Note that we need a fake main for doc tests to build
+/// # fn main() {}
 /// ```
 #[proc_macro_attribute]
 pub fn qsignals(_args: TokenStream, _input: TokenStream) -> TokenStream {
@@ -78,28 +92,38 @@ pub fn qsignals(_args: TokenStream, _input: TokenStream) -> TokenStream {
 ///
 /// # Example
 ///
-/// ```ignore
-/// #[cxx_qt::bridge(namespace = "cxx_qt::my_object")]
+/// ```rust
+/// #[cxx_qt::bridge]
 /// mod my_object {
 ///     #[cxx_qt::qobject]
-///     struct MyObject;
+///     #[derive(Default)]
+///     # // Note that we can't use properties as this confuses the linker on Windows
+///     pub struct MyObject;
 /// }
+///
+/// # // Note that we need a fake main for doc tests to build
+/// # fn main() {}
 /// ```
 ///
 /// You can also specify a custom base class by using `#[cxx_qt::qobject(base = "QStringListModel")]`, you must then use CXX to add any includes needed.
 ///
 /// # Example
 ///
-/// ```ignore
-/// #[cxx_qt::bridge(namespace = "cxx_qt::my_object")]
+/// ```rust
+/// #[cxx_qt::bridge]
 /// mod my_object {
 ///     #[cxx_qt::qobject(base = "QStringListModel")]
-///     struct MyModel;
+///     #[derive(Default)]
+///     # // Note that we can't use properties as this confuses the linker on Windows
+///     pub struct MyModel;
 ///
 ///     unsafe extern "C++" {
 ///         include!(<QtCore/QStringListModel>);
 ///     }
 /// }
+///
+/// # // Note that we need a fake main for doc tests to build
+/// # fn main() {}
 /// ```
 #[proc_macro_attribute]
 pub fn qobject(_args: TokenStream, _input: TokenStream) -> TokenStream {
@@ -114,25 +138,34 @@ pub fn qobject(_args: TokenStream, _input: TokenStream) -> TokenStream {
 /// details.
 ///
 /// # Example
-/// ``` ignore
+/// ``` rust
 /// #[cxx_qt::bridge]
 /// mod my_object {
+///     extern "C++" {
+///         include!("cxx-qt-lib/qmodelindex.h");
+///         type QModelIndex = cxx_qt_lib::QModelIndex;
+///     }
+///
 ///     #[cxx_qt::qobject(base="QAbstractListModel")]
 ///     #[derive(Default)]
-///     struct MyObject;
+///     # // Note that we can't use properties as this confuses the linker on Windows
+///     pub struct MyObject;
 ///
 ///     #[cxx_qt::inherit]
 ///     extern "C++" {
 ///         // Unsafe to call
-///         unsafe fn begin_insert_rows(self: Pin<&mut Self>, parent: &QModelIndex, first: i32, last: i32);
+///         unsafe fn begin_insert_rows(self: Pin<&mut qobject::MyObject>, parent: &QModelIndex, first: i32, last: i32);
 ///     }
 ///
 ///     #[cxx_qt::inherit]
 ///     unsafe extern "C++" {
 ///         // Safe to call - you are responsible to ensure this is true!
-///         fn end_insert_rows(self: Pin<&mut Self>);
+///         fn end_insert_rows(self: Pin<&mut qobject::MyObject>);
 ///     }
 /// }
+///
+/// # // Note that we need a fake main for doc tests to build
+/// # fn main() {}
 /// ```
 #[proc_macro_attribute]
 pub fn inherit(_args: TokenStream, _input: TokenStream) -> TokenStream {