Place all objects and passthrough items in the same block, to pass through module docs and cfg (C++Qt only)

Author: BenFordTytherington

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

@@ -10,7 +10,7 @@ use crate::{
     syntax::path::path_compare_str,
 };
 use quote::quote;
-use syn::{parse_quote, Attribute, Result};
+use syn::{parse_quote, Attribute, Item, Result};
 
 impl GeneratedRustFragment {
     pub fn from_extern_cxx_qt(
@@ -22,76 +22,88 @@ impl GeneratedRustFragment {
         } else {
             quote! {}
         };
+        let extern_block_docs = &extern_cxxqt_block.docs;
 
         // Add the pass through blocks
         let unsafety = &extern_cxxqt_block.unsafety;
         let items = &extern_cxxqt_block.passthrough_items;
-        let mut generated = extern_cxxqt_block
-            .qobjects
-            .iter()
-            .map(|ty| -> Result<GeneratedRustFragment> {
-                let mut generated = vec![];
-                let qobject_names = QObjectNames::from_extern_qobject(ty, type_names)?;
 
-                generated.push(GeneratedRustFragment::generate_casting_impl(
-                    &qobject_names,
-                    type_names,
-                    &ty.name,
-                    &ty.base_class,
-                )?);
+        let mut qobject_items: Vec<Item> = vec![];
+        let mut cxx_qt_mod = vec![];
+        let mut cxx_mod = vec![];
+        for obj in &extern_cxxqt_block.qobjects {
+            let qobject_names = QObjectNames::from_extern_qobject(obj, type_names)?;
 
-                let namespace = if let Some(namespace) = &ty.name.namespace() {
-                    quote! { #[namespace = #namespace ] }
-                } else {
-                    quote! {}
-                };
-                let cpp_name = &ty.name.cxx_unqualified();
-                let rust_name = &ty.name.rust_unqualified();
-                let vis = &ty.declaration.vis;
-                let ident = &ty.name.rust_unqualified();
-                let cxx_name = if &rust_name.to_string() == cpp_name {
-                    quote! {}
-                } else {
-                    let cxx_name = cpp_name.to_string();
-                    quote! {
-                        #[cxx_name = #cxx_name]
-                    }
-                };
-                let cfgs: Vec<&Attribute> = ty
-                    .declaration
-                    .attrs
-                    .iter()
-                    .filter(|attr| path_compare_str(attr.meta.path(), &["cfg"]))
-                    .collect();
-                let docs: Vec<&Attribute> = ty
-                    .declaration
-                    .attrs
-                    .iter()
-                    .filter(|attr| path_compare_str(attr.meta.path(), &["doc"]))
-                    .collect();
-                generated.push(GeneratedRustFragment::from_cxx_item(parse_quote! {
-                    #extern_block_namespace
-                    #unsafety extern "C++" {
-                        #namespace
-                        #cxx_name
-                        #(#cfgs)*
-                        #(#docs)*
-                        #vis type #ident;
-                    }
-                }));
-                Ok(GeneratedRustFragment::flatten(generated))
-            })
-            .collect::<Result<Vec<_>>>()?;
+            let casting = GeneratedRustFragment::generate_casting_impl(
+                &qobject_names,
+                type_names,
+                &obj.name,
+                &obj.base_class,
+            )?;
+            cxx_mod.extend(casting.cxx_mod_contents);
+            cxx_qt_mod.extend(casting.cxx_qt_mod_contents);
 
-        if !items.is_empty() {
-            generated.push(GeneratedRustFragment::from_cxx_item(parse_quote! {
-                #extern_block_namespace
-                #unsafety extern "C++" {
-                    #(#items)*
+            let namespace = if let Some(namespace) = &obj.name.namespace() {
+                quote! { #[namespace = #namespace ] }
+            } else {
+                quote! {}
+            };
+            let cpp_name = &obj.name.cxx_unqualified();
+            let rust_name = &obj.name.rust_unqualified();
+            let vis = &obj.declaration.vis;
+            let ident = &obj.name.rust_unqualified();
+            let cxx_name = if &rust_name.to_string() == cpp_name {
+                quote! {}
+            } else {
+                let cxx_name = cpp_name.to_string();
+                quote! {
+                    #[cxx_name = #cxx_name]
                 }
-            }));
+            };
+            let cfgs: Vec<&Attribute> = obj
+                .declaration
+                .attrs
+                .iter()
+                .filter(|attr| path_compare_str(attr.meta.path(), &["cfg"]))
+                .collect();
+            let docs: Vec<&Attribute> = obj
+                .declaration
+                .attrs
+                .iter()
+                .filter(|attr| path_compare_str(attr.meta.path(), &["doc"]))
+                .collect();
+            qobject_items.push(parse_quote! {
+                #namespace
+                #cxx_name
+                #(#cfgs)*
+                #(#docs)*
+                #vis type #ident;
+            });
         }
 
+        let passthrough_items = if !items.is_empty() {
+            quote! {
+                #(#items)*
+            }
+        } else {
+            quote! {}
+        };
+
+        cxx_mod.push(parse_quote! {
+            #extern_block_namespace
+            #(#extern_block_docs)*
+            #unsafety extern "C++" {
+                #(#qobject_items)*
+
+                #passthrough_items
+            }
+        });
+
+        let mut generated = vec![GeneratedRustFragment {
+            cxx_mod_contents: cxx_mod,
+            cxx_qt_mod_contents: cxx_qt_mod,
+        }];
+
         // Build the signals
         for signal in &extern_cxxqt_block.signals {
             let qobject_name = type_names.lookup(&signal.qobject_ident)?;

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

@@ -28,7 +28,7 @@ impl GeneratedRustFragment {
         let namespace_idents = NamespaceName::from(qobject);
 
         let mut generated = vec![
-            generate_qobject_definitions(&qobject_names, &qobject.cfgs)?,
+            generate_qobject_definitions(&qobject_names, &qobject.cfgs, &qobject.docs)?,
             generate_rust_properties(
                 &qobject.properties,
                 &qobject_names,
@@ -88,6 +88,7 @@ impl GeneratedRustFragment {
 fn generate_qobject_definitions(
     qobject_idents: &QObjectNames,
     cfgs: &[Attribute],
+    docs: &[Attribute],
 ) -> Result<GeneratedRustFragment> {
     let cpp_class_name_rust = &qobject_idents.name.rust_unqualified();
     let cpp_class_name_cpp = &qobject_idents.name.cxx_unqualified();
@@ -106,6 +107,15 @@ fn generate_qobject_definitions(
         }
     };
 
+    let maybe_docs = if docs.is_empty() {
+        quote! {}
+    } else {
+        quote! {
+            #[doc = "\n"]
+            #(#docs)*
+        }
+    };
+
     Ok(GeneratedRustFragment {
         cxx_mod_contents: vec![
             parse_quote! {
@@ -116,6 +126,7 @@ fn generate_qobject_definitions(
                     #[doc = "Use this type when referring to the QObject as a pointer"]
                     #[doc = "\n"]
                     #[doc = "See the book for more information: <https://kdab.github.io/cxx-qt/book/concepts/generated_qobject.html>"]
+                    #maybe_docs
                     #namespace
                     #cxx_name
                     #(#cfgs)*
@@ -130,6 +141,7 @@ fn generate_qobject_definitions(
                     // but to apply it to only certain types, it is needed here too
                     #namespace
                     #(#cfgs)*
+                    #(#docs)*
                     type #rust_struct_name_rust;
                 }
             },

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

@@ -3,6 +3,7 @@
 //
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
+use crate::parser::extract_docs;
 use crate::{
     parser::{
         externqobject::ParsedExternQObject, require_attributes, signals::ParsedSignal,
@@ -11,14 +12,17 @@ use crate::{
     syntax::{attribute::attribute_get_path, expr::expr_to_string},
 };
 use syn::{
-    spanned::Spanned, Error, ForeignItem, ForeignItemFn, Ident, ItemForeignMod, Result, Token,
+    spanned::Spanned, Attribute, Error, ForeignItem, ForeignItemFn, Ident, ItemForeignMod, Result,
+    Token,
 };
 
 /// Representation of an extern "C++Qt" block
 #[derive(Default)]
 pub struct ParsedExternCxxQt {
     /// The namespace of the type in C++.
     pub namespace: Option<String>,
+    /// The Top level docs on the module
+    pub docs: Vec<Attribute>,
     /// Whether this block has an unsafe token
     pub unsafety: Option<Token![unsafe]>,
     /// Items which can be passed into the extern "C++Qt" block
@@ -38,9 +42,11 @@ impl ParsedExternCxxQt {
         // TODO: support cfg on foreign mod blocks
         let attrs = require_attributes(
             &foreign_mod.attrs,
-            &["namespace", "auto_cxx_name", "auto_rust_name"],
+            &["namespace", "doc", "auto_cxx_name", "auto_rust_name"],
         )?;
 
+        let docs = extract_docs(&foreign_mod.attrs);
+
         let auto_case = CaseConversion::from_attrs(&attrs)?;
 
         let namespace = attrs
@@ -52,6 +58,7 @@ impl ParsedExternCxxQt {
 
         let mut extern_cxx_block = ParsedExternCxxQt {
             namespace,
+            docs,
             unsafety: foreign_mod.unsafety,
             ..Default::default()
         };

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

@@ -11,7 +11,7 @@ use crate::{
 #[cfg(test)]
 use quote::format_ident;
 
-use crate::parser::{parse_base_type, CaseConversion};
+use crate::parser::{extract_docs, parse_base_type, CaseConversion};
 use syn::{Attribute, Error, Ident, Meta, Result};
 
 /// Metadata for registering QML element
@@ -44,6 +44,8 @@ pub struct ParsedQObject {
     pub declaration: ForeignTypeIdentAlias,
     /// Cfgs for the object
     pub cfgs: Vec<Attribute>,
+    /// Docs for the object
+    pub docs: Vec<Attribute>,
 }
 
 impl ParsedQObject {
@@ -75,6 +77,7 @@ impl ParsedQObject {
                 ident_right: format_ident!("MyObjectRust"),
             },
             cfgs: vec![],
+            docs: vec![],
         }
     }
 
@@ -86,8 +89,8 @@ impl ParsedQObject {
         auto_case: CaseConversion,
     ) -> Result<Self> {
         let attributes = require_attributes(&declaration.attrs, &Self::ALLOWED_ATTRS)?;
-        // TODO: handle docs through to generation
         let cfgs = extract_cfgs(&declaration.attrs);
+        let docs = extract_docs(&declaration.attrs);
 
         let has_qobject_macro = attributes.contains_key("qobject");
 
@@ -126,6 +129,7 @@ impl ParsedQObject {
             qml_metadata,
             has_qobject_macro,
             cfgs,
+            docs,
         })
     }
 

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

@@ -92,6 +92,7 @@ pub mod ffi {
     }
 
     #[namespace = ""]
+    /// Top level docs for a module
     unsafe extern "C++Qt" {
         #[qobject]
         type QPushButton;
@@ -102,6 +103,7 @@ pub mod ffi {
         #[namespace = "mynamespace"]
         #[cxx_name = "ExternObjectCpp"]
         #[qobject]
+        /// An external object with some docs on it
         type ExternObject;
 
         #[qsignal]
@@ -130,6 +132,7 @@ pub mod ffi {
         #[qobject]
         #[namespace = "second_object"]
         #[qproperty(i32, property_name, cxx_name = "propertyName")]
+        /// The second QObject with some different docs on it
         type SecondObject = super::SecondObjectRust;
     }
 

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

@@ -103,8 +103,6 @@ mod inheritance {
     }
     extern "C++" {
         type QPushButton;
-    }
-    extern "C++" {
         include ! (< QtWidgets / QPushButton >);
     }
     extern "C++" {

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

@@ -201,11 +201,14 @@ pub mod ffi {
         #[doc = "Use this type when referring to the QObject as a pointer"]
         #[doc = "\n"]
         #[doc = "See the book for more information: <https://kdab.github.io/cxx-qt/book/concepts/generated_qobject.html>"]
+        #[doc = "\n"]
+        #[doc = " The second QObject with some different docs on it"]
         #[namespace = "second_object"]
         type SecondObject;
     }
     extern "Rust" {
         #[namespace = "second_object"]
+        #[doc = " The second QObject with some different docs on it"]
         type SecondObjectRust;
     }
     extern "Rust" {
@@ -381,11 +384,6 @@ pub mod ffi {
         #[namespace = "rust::cxxqt1"]
         unsafe fn cxx_qt_ffi_QPushButton_downcastPtr(base: *const QObject) -> *const QPushButton;
     }
-    #[namespace = ""]
-    unsafe extern "C++" {
-        #[namespace = "cxx_qt::multi_object"]
-        type QPushButton;
-    }
     extern "C++" {
         #[doc(hidden)]
         #[cxx_name = "upcastPtr"]
@@ -400,9 +398,13 @@ pub mod ffi {
         ) -> *const ExternObject;
     }
     #[namespace = ""]
+    #[doc = " Top level docs for a module"]
     unsafe extern "C++" {
+        #[namespace = "cxx_qt::multi_object"]
+        type QPushButton;
         #[namespace = "mynamespace"]
         #[cxx_name = "ExternObjectCpp"]
+        #[doc = " An external object with some docs on it"]
         type ExternObject;
     }
     unsafe extern "C++" {

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

@@ -196,8 +196,6 @@ mod ffi {
         #[namespace = "cxx_qt::my_object"]
         #[doc = " QTimer"]
         type QTimer;
-    }
-    unsafe extern "C++" {
         include ! (< QtCore / QTimer >);
     }
     unsafe extern "C++" {