Generated qobject module has no documentation, triggering #![warn(missing_docs)]

[ruifengx]

The generated qobject module has no documentation. In a library with global #![warn(missing_docs)] lint enabled, this results in a warning per bridge module, and the warning cannot be easily silenced (because we cannot attach attributes to the qobject module). Currently, the only workaround is to #![allow(missing_docs)] in the parent module (that is, the module containing the bridge module and therefore the generated qobject module), which would silence the warning for too many things.

I can think of three possible solutions:

• (easiest and also preferred) include a documentation comment like /// Automatically generated QObject types. or at least #[allow(missing_docs)] in the generated code;
• allow specifying arbitrary attributes on the qobject module (I feel this might be an overkill);
• add an option to make the generated qobject module private, and let the user re-export the types they need.

[ahayzen-kdab]

I think the best option for now is to include a basic documentation in the generated types. As allowing custom docs is probably overkill for now as you state, and making the generated qobject private then means it can't be used for using them in pointers etc.

[ruifengx]

making the generated qobject private then means it can't be used for using them in pointers etc.

Just a side note: pub items in private mod is allowed to appear in public interfaces, as illustrated with the following code (link to Rust Playground):

mod private { pub struct Item; }
pub fn test() -> private::Item { private::Item }

This does however make private::Item unnameable outside the defining crate (or more precisely, wherever the module private is not accessible). In fact, this is how sealed traits are usually implemented in Rust. If taking this approach, the Item can still be made publicly available (by the user of this crate, explicitly) with a pub use statement or pub type alias. That said, I do agree that it suffice to just have some basic documentation to silence the warnings.

[ahayzen-kdab]

Internally there is a bit of complexity of what is pub and not, as some things need to be placed in the right place for CXX to find them and some for developers to be able to reach.

This could be reviewed separately whether it can be improved, but for now I've just added docs in and enabled deny(missing_docs) on one of our examples so we can ensure that things build with this enabled ( #518 ) .