Details
-
User Story
-
Resolution: Unresolved
-
P2: Important
-
None
-
None
-
2891c622c (dev), 436affa3c (dev), 3548d4f93 (dev), 9caedaa1a (dev), 1e745d04f (dev)
Description
The documentation of our template APIs today has two major shortcomings:
- We cannot document the template parameters in the same way as we do function parameters
Ie. in QHash (https://doc.qt.io/qt-6/qhash.html), we document the type as template <typename Key, typename T> class QHash but in the description of the class we don't document Key and T, and instead just say: "QHash<Key, T> is one of Qt's generic container classes. It stores (key, value) pairs and provides very fast lookup of the value associated with a key.". It's up to the reader to figure out that T is the type of the value.
This is a bigger issue with template functions in non-template classes, where we don't have standardised wording, and also no qdoc support to make sure that we have a \a T equivalent for all template parameters.
- We have no standard way to document constraints for the template types
We increasingly SFINAE out template instances from the overload set if the type doesn't meet the requirements. As we can't use C++20 concepts yet, we do that via std::enable_if and hide that complexity from the documentation explicitly via #ifndef QT_QDOC preprocessor symbols.
E.g. a constraint today might be implemented as
template <typename T
#ifndef QT_QDOC
, std::enable_if_t<std::is_trivially_constructible_v<T>, bool> = true
#endif
>
void foo(T &&t)
{}
And then the documentation will not mention that T needs to be trivially constructible.
But even without C++ concepts, we could express constraints in a way that qdoc can understand. This requires a bit of research into how to make this so that it applies also when we finally move to C++20.
In fact, qdoc could already use C++20, so we might just as well express constraints using C++20 syntax:
template <typename T #ifndef QT_QDOC , std::enable_if_t<std::is_trivially_constructible_v<T>, bool> = true > #else > requires (std::is_trivially_constructible_v<T>) #endif void foo(T &&t) {}
and that way start building a concepts library already now, that qdoc can then refer to. Once we move to C++ 20, we will have a good starting point as well as good documentation.
Attachments
Issue Links
- relates to
-
QTBUG-106871 As a developer of Qt, I'd like to have guidance on how to properly document constrained templates
-
- Closed
-
Gerrit Reviews
For Gerrit Dashboard: QTBUG-117881 | ||||||
---|---|---|---|---|---|---|
# | Subject | Branch | Project | Status | CR | V |
520261,6 | QDoc: Add a regression suite for templated callables | dev | qt/qttools | Status: MERGED | +2 | 0 |
520262,6 | QDoc: Add a more granular representation for template declarations | dev | qt/qttools | Status: MERGED | +2 | 0 |
521625,6 | QDoc: Allow RelaxedTemplateDeclaration to be rebuilt as string | dev | qt/qttools | Status: MERGED | +2 | 0 |
521626,7 | QDoc: Use a more granular representation for template declarations | dev | qt/qttools | Status: MERGED | +2 | 0 |
521627,7 | QDoc: Consider template declarations when matching a callable | dev | qt/qttools | Status: MERGED | +2 | 0 |