Uploaded image for project: 'Qt'
  1. Qt
  2. QTBUG-106871

As a developer of Qt, I'd like to have guidance on how to properly document constrained templates

    XMLWordPrintable

Details

    Description

      Constrained templates are those that either use std::enable_if (openly, or hidden in a if_x<T> = true template alias), or, come C++20, requires clauses.

      We need to make sure that qdoc understands these enable_if and later requires clauses and produces sensible documentation from them.

      Currently, we either ignore the issue and hope that qdoc will produce something sensible from the C++ declaration, or we fake some unconstrained versions of the function under #ifdef Q_QDOC. The former obviously works in that qdoc copied the enable_if verbatim (https://doc.qt.io/qt-6/qstringview.html#QStringView-3), but since the constraint isn't clickable, the user is left wondering what the heck that thing is. The latter is a lie to the user, and means she needs to look into the header instead of the docs when some overloading/SFINAE goes wrong for her.

      So, we need to up our game here.

      Please come up with a way to document concepts (not just the C++20 ones, which are a ways out, still, but also incidental C++17 ones like QStringView's if_compatible_char), get stakeholder approval, and implement what's missing in qdoc to support it.

      Attachments

        No reviews matched the request. Check your Options in the drop-down menu of this sections header.

        Activity

          People

            docteam Qt Documentation Team
            mmutz Marc Mutz
            Vladimir Minenko Vladimir Minenko
            Alex Blasche Alex Blasche
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

            Dates

              Created:
              Updated:

              Gerrit Reviews

                There are no open Gerrit changes