From 10677ce1c8b834530f95602a2870fa5142a36437 Mon Sep 17 00:00:00 2001 From: Andrew Hayzen Date: Fri, 1 Mar 2024 15:09:14 +0000 Subject: [PATCH] cxx-qt-gen: enable missing_docs and fix missing docs --- crates/cxx-qt-gen/src/generator/cpp/fragment.rs | 11 ++++++++++- crates/cxx-qt-gen/src/generator/cpp/mod.rs | 1 + crates/cxx-qt-gen/src/generator/rust/mod.rs | 1 + crates/cxx-qt-gen/src/lib.rs | 9 +++++++-- crates/cxx-qt-gen/src/parser/mod.rs | 6 +++--- crates/cxx-qt-gen/src/syntax/mod.rs | 2 +- crates/cxx-qt-gen/src/syntax/qtfile.rs | 4 ++++ crates/cxx-qt-gen/src/syntax/qtitem.rs | 3 +-- 8 files changed, 28 insertions(+), 9 deletions(-) diff --git a/crates/cxx-qt-gen/src/generator/cpp/fragment.rs b/crates/cxx-qt-gen/src/generator/cpp/fragment.rs index b62bf3b6b..27bd5590d 100644 --- a/crates/cxx-qt-gen/src/generator/cpp/fragment.rs +++ b/crates/cxx-qt-gen/src/generator/cpp/fragment.rs @@ -4,9 +4,18 @@ // SPDX-License-Identifier: MIT OR Apache-2.0 #[derive(PartialEq, Eq, Debug)] +/// A fragment of C++ code pub enum CppFragment { - Pair { header: String, source: String }, + /// A fragment which only both a header and a source + Pair { + /// The header of the fragment + header: String, + /// The source of the fragment + source: String, + }, + /// A fragment which only has a header Header(String), + /// A fragment which only has a source Source(String), } diff --git a/crates/cxx-qt-gen/src/generator/cpp/mod.rs b/crates/cxx-qt-gen/src/generator/cpp/mod.rs index eed396483..0dd8028e7 100644 --- a/crates/cxx-qt-gen/src/generator/cpp/mod.rs +++ b/crates/cxx-qt-gen/src/generator/cpp/mod.rs @@ -39,6 +39,7 @@ pub struct GeneratedCppBlocks { } impl GeneratedCppBlocks { + /// Create a [GeneratedCppBlocks] from the given [Parser] object pub fn from(parser: &Parser) -> Result { let mut includes = BTreeSet::new(); diff --git a/crates/cxx-qt-gen/src/generator/rust/mod.rs b/crates/cxx-qt-gen/src/generator/rust/mod.rs index 7a2b7b7f5..c6c50cc0a 100644 --- a/crates/cxx-qt-gen/src/generator/rust/mod.rs +++ b/crates/cxx-qt-gen/src/generator/rust/mod.rs @@ -33,6 +33,7 @@ pub struct GeneratedRustBlocks { } impl GeneratedRustBlocks { + /// Create a [GeneratedRustBlocks] from the given [Parser] object pub fn from(parser: &Parser) -> Result { let mut fragments = vec![]; fragments.extend( diff --git a/crates/cxx-qt-gen/src/lib.rs b/crates/cxx-qt-gen/src/lib.rs index b2861f045..1ee1754c9 100644 --- a/crates/cxx-qt-gen/src/lib.rs +++ b/crates/cxx-qt-gen/src/lib.rs @@ -3,6 +3,11 @@ // SPDX-FileContributor: Gerhard de Clercq // // SPDX-License-Identifier: MIT OR Apache-2.0 + +#![deny(missing_docs)] + +//! The cxx-qt-gen crate provides methods for generated C++ and Rust code from a TokenStream. + mod generator; mod naming; mod parser; @@ -13,8 +18,8 @@ pub use generator::{ cpp::{fragment::CppFragment, GeneratedCppBlocks}, rust::GeneratedRustBlocks, }; -pub use parser::{qobject::QmlElementMetadata, Parser}; -pub use syntax::{parse_qt_file, CxxQtItem}; +pub use parser::Parser; +pub use syntax::{parse_qt_file, CxxQtFile, CxxQtItem}; pub use writer::{cpp::write_cpp, rust::write_rust}; pub use syn::{Error, Result}; diff --git a/crates/cxx-qt-gen/src/parser/mod.rs b/crates/cxx-qt-gen/src/parser/mod.rs index b4579efce..bdd5f06fc 100644 --- a/crates/cxx-qt-gen/src/parser/mod.rs +++ b/crates/cxx-qt-gen/src/parser/mod.rs @@ -30,11 +30,11 @@ use syn::{ /// [syn::Item]'s that are not handled specially by CXX-Qt are passed through for CXX to process. pub struct Parser { /// The module which unknown (eg CXX) blocks are stored into - pub passthrough_module: ItemMod, + pub(crate) passthrough_module: ItemMod, /// Any CXX-Qt data that needs generation later - pub cxx_qt_data: ParsedCxxQtData, + pub(crate) cxx_qt_data: ParsedCxxQtData, /// all type names that were found in this module, including CXX types - pub type_names: TypeNames, + pub(crate) type_names: TypeNames, /// The stem of the file that the CXX headers for this module will be generated into pub cxx_file_stem: String, } diff --git a/crates/cxx-qt-gen/src/syntax/mod.rs b/crates/cxx-qt-gen/src/syntax/mod.rs index e5cada855..9677ae0ca 100644 --- a/crates/cxx-qt-gen/src/syntax/mod.rs +++ b/crates/cxx-qt-gen/src/syntax/mod.rs @@ -13,5 +13,5 @@ mod qtitem; pub mod safety; pub mod types; -pub use qtfile::parse_qt_file; +pub use qtfile::{parse_qt_file, CxxQtFile}; pub use qtitem::CxxQtItem; diff --git a/crates/cxx-qt-gen/src/syntax/qtfile.rs b/crates/cxx-qt-gen/src/syntax/qtfile.rs index b14214cc7..481bd46b0 100644 --- a/crates/cxx-qt-gen/src/syntax/qtfile.rs +++ b/crates/cxx-qt-gen/src/syntax/qtfile.rs @@ -9,8 +9,11 @@ use quote::{ToTokens, TokenStreamExt}; use syn::parse::{Parse, ParseStream}; use syn::{AttrStyle, Attribute, Result}; +/// Representation of a CxxQtFile as Syn items pub struct CxxQtFile { + /// A vector of [syn::Attribute] in the file pub attrs: Vec, + /// A vector of [CxxQtItem] items in the file pub items: Vec, } @@ -40,6 +43,7 @@ impl ToTokens for CxxQtFile { } } +/// Parse the given [std::path::Path] into a [CxxQtFile] pub fn parse_qt_file(path: impl AsRef) -> Result { let source = std::fs::read_to_string(path.as_ref()).unwrap_or_else(|err| { // todo: fixme with a proper error propagation diff --git a/crates/cxx-qt-gen/src/syntax/qtitem.rs b/crates/cxx-qt-gen/src/syntax/qtitem.rs index 58fb5c7f0..2f113979e 100644 --- a/crates/cxx-qt-gen/src/syntax/qtitem.rs +++ b/crates/cxx-qt-gen/src/syntax/qtitem.rs @@ -10,8 +10,7 @@ use syn::parse::{Parse, ParseStream}; use syn::{Attribute, Item, ItemMod, Result, Token, Visibility}; #[derive(Clone, PartialEq, Eq)] -// This warning is triggered when running clippy on crates that depend on cxx-qt-gen, -// but not when running clippy on cxx-qt-gen. +/// Representation of either a Syn Item, a CXX module, or a CXX-Qt module pub enum CxxQtItem { /// A normal syntax item that we pass through Item(Item),