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

QDoc: Allow producing documentation sets for specific C++ standards

    XMLWordPrintable

Details

    • Task
    • Resolution: Invalid
    • P3: Somewhat important
    • None
    • None
    • None

    Description

      Currently QDoc hard-codes the C++ standard that it uses to build the documentation.

      For codebases where different standards have different interfaces this means that the documentation will be unable to provide correct information to a user that uses a different standard than the one that QDoc uses.

       

      One such example might be the recently introduced support for comparison operators, where, for compatibility reason, Qt built on C+17 and Qt built on C+20 will provide a different interface for some of the generated elements, such a `qCompareThreeWay`.

       

      A user of the documentation that reads the documentation, which is currently built for a C++20 standard, might find that the documentation might not represent what they are actually encountering in their own code, degrading the usability of the documentation itself and the experience of the user.

       

      QDoc should allow to customize the standard that is used for building, so that documentation sets for different standards can be easily built on demand.

       

      This might require multiple changes, from QDoc itself to our publishing infrastructure.

       

      • QDoc should allow a user to set the desired standard for a documentation build. This could be provided through the use of a configuration variable in the project itself, through a command line argument to a QDoc invocation or through an environment variable.
      • QDoc should provide some way for a user writing a documentation piece to customize their writings based on the used standard. QDoc already defines a `Q_QDOC` symbol to allow specializing code for QDoc specifically. This could be expanded to allow for standard specific customizations by providing defining multiple standard-specific version of the symbol. QDoc should further allow a documentation block to be customized by version. While QDoc provides an "\if" command that can be used for this purpose, it doesn't use the same definitions that the project parsing uses, so QDoc might be modified to provide mirrored definition for `Q_QDOC_X` symbols to be used with `\if`.
      • The publishing infrastructure should be enhanced to build documentation sets with different standards, making it as easy as possible to support builds with multiple standards.
      • The documentation sets that the user can access from "doc.qt.io" should show information about different standards. Possibly, showing the differences between standards in the same document would be optimal, to enhance discoverability and reduce the friction for the user. QDoc is not currently architectured so that this will be possible to implement, but it might be possible to implement such a feature, with some changes, as a post-processing step on the output documentation that QDoc produces. Alternatively, multiple documentation sets might be parameterized by the standard they were built with, allowing the user to choose what they want to look at through means similar to a version selector.

      A mixture of those changes or possibly an entirely different solution is  expected to be required to complete this task.
       

      Attachments

        Issue Links

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

          Activity

            People

              docinfrastructure Documentation Infrastructure Team
              diseraluca Luca Di Sera
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved:

                Gerrit Reviews

                  There are no open Gerrit changes