Qt Contributors Summit 2024 - A Closer Look at QDoc and the Documentation Infrastructure Team

At the Qt Contributors Summit 2024, in a session together with Nicholas Bennett, I had the opportunity to present the latest developments in QDoc and give an overview of the Documentation Infrastructure team's work. Our team, though small, plays a vital role in maintaining and improving the tools and infrastructure behind Qt's comprehensive documentation. In this post, I’ll walk you through some key points from my part of the presentation, focusing on our recent developments and future plans for QDoc.

Meet the Documentation Infrastructure Team

Our team is small but diverse, comprising both developers and technical writers. I’m a software engineer on the team, working alongside Topi, our team leader and QDoc maintainer, as well as technical writers Venu, Andreas, Safiyyah, and Jerome. 

With only 1.5 developers — myself and Topi, who splits his time between management and development — progress in QDoc development can be slower than we'd like. We recently "lost" a team member who transitioned to the QML compiler team, but we are hopeful to add another software engineer soon, which will help us tackle more tasks at a faster pace.

Infrastructure

One of the key responsibilities of our team is managing the documentation builds in COIN, Qt’s CI system. They've helped us reduce the amount of documentation-related warnings to near none, and have
served us well for years. That the integrations are module by module means we can't perform cross-module documentation builds, and we ignore any warnings about broken links because of this. To mitigate that, we run daily snapshots that provide diagnostics, including warnings about broken links and suggestions from the text linter 'vale.' This helps maintain a higher standard of documentation for the entire Qt ecosystem.

Another significant aspect of our work involves provisioning the Clang libraries used to build QDoc. These libraries are provided on download.qt.io and are essential for building the QDoc binary we run in COIN, and the one we ship with the installer. If you're building QDoc yourself, our recommendation is that you grab the package we provide for the platform and toolchain you're on, and link against that. The provisioning process can be tricky at times, especially with keeping the latest development version aligned with what's running in COIN.

QDoc: Recent Developments

Our team has been hard at work enhancing QDoc in several areas, ranging from new commands to preparing for the latest C++ standards.

- New Commands: We’ve introduced a series of new and improved QDoc commands, such as improved template overload resolution for the \fn command,  \compares and \compareswith commands for documenting C++ type comparison results, and the \details command for expanding content. The \nativetype command replaces the older \instantiates command, providing a more descriptive and robust way to generate documentation; the old command delegates to the new one, so existing users aren't affected. Additionally, the \tm command was added to help mark trademarks.
  
- Preparing for C++20: We have transitioned from Clang 15 to Clang 18, as that helps us prepare for C++20. Meanwhile, we require Clang 17 as the minimum version for Qt 6.8. We also started a partial transition from Clang's C-based API to its C++ interfaces, which we are expanding on, that has improved our ability to implement features related to the latest development in the language.

- Refactoring and Bug Fixing: Alongside these feature updates, we’ve dedicated time to refactoring and addressing bugs, ensuring QDoc remains stable and maintainable for the long term. We’ve also introduced new end-to-end tests to enhance the reliability of QDoc.

What’s Next for QDoc

Looking to the future, our focus is on several key areas:

- QML and the DOM API: We’re exploring a shift from the AST-based parser to the evolving DOM API for QML, aiming to achieve a sort of "feature parity" in terms of what QDoc generates for QML and C++ documentation. We believe this will result in more comprehensive and consistent documentation for QML-based projects.

- Performance Optimizations: We’re actively working on performance improvements that should significantly speed up documentation generation, making it faster and more efficient to work with QDoc.

- Supporting New C++ Features: As C++ continues to evolve, we’re committed to ensuring that QDoc stays aligned with new language features. This is essential for offering up-to-date documentation tooling as Qt moves to newer C++ standards. Although Qt itself isn't likely to require C++20 in the immediate future, we expect that it'll happen eventually. At that time, QDoc must be ready.

Collaborations and Community Involvement

During the presentation, a lively discussion unfolded about potential future developments. Cristian asked if we track any planned or missing QDoc commands in an epic. We don't do that, as we tend to implement
them as need arises. Tuukka raised an interesting point about video documentation, sparking thoughts on how we could provide more multimedia resources to complement traditional text-based docs.

Additionally, we’ve received interest from the KDE community about using QDoc for their documentation, as QDoc’s close integration with Qt might address some of the limitations they face with their current Doxygen-based system. Nicholas from KDE shared that QML documentation is not well supported in Doxygen, and QDoc could be a valuable tool for them. We're very happy to learn about this, and will offer the support we can to help make the transition.

Conclusion

In closing, we’ve made significant strides with QDoc, but there’s still much work to be done. Whether it’s aligning with the latest C++ standards, improving performance, or enhancing QML support, our team is committed to making QDoc a powerful and reliable tool for the Qt ecosystem. We’re always open to feedback, ideas, and collaboration from the community. If you have any questions or suggestions, we’d love to hear from you!

Let’s continue the conversation and push the boundaries of what Qt documentation can achieve. Feel free to comment below with your thoughts or reach out directly if you’d like to contribute to our ongoing efforts!