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

Documentation typos, errors and improvements

    XMLWordPrintable

Details

    • Bug
    • Resolution: Fixed
    • P2: Important
    • 6.5, 6.6.0 FF
    • 6.5.0
    • Documentation
    • None
    • 37283ea8c (dev), 86937f931 (dev), d863a137e (6.5), 346573501 (dev), 17d1e2597 (dev), ab4125685 (dev), 2bba2f7dc (6.5), e0154ee71 (6.5), f845c76c7 (6.5), 9b7120f0e (6.5), 3abfd4aa7 (dev), e5fb96079 (6.5)

    Description

      I noticed the following minor errors while browsing the CMake parts of the 6.5.0 docs. Probably easiest to address them all as a single task, so I've collected them here in one place for easy reference.

      • [Fixed]: In the CMake property reference page, there is a typo in the global properties section:
        QT_QMLLLINTER_TARGETS_FOLDER --> QT_QMLLINTER_TARGETS_FOLDER (note the extra "L" in the current docs).
      • [Fixed]: In the CMake variable reference page, the example of the per-module variables lists Qt6Widgets_VERSION_STRING, but there is no such variable. It probably was meant to be Qt6Widgets_VERSION.
      • The qt_finalize_target() docs mention that it is ordinarily invoked as part of a call to qt_add_executable() or qt_add_library(). For completeness, it should probably also mention qt_add_plugin().
      • Some commands and variables seem to have been in technology preview since 6.2 or 6.3, but are still listed as tech preview in the 6.5.0 LTS release. Given that they are part of the LTS release and have been around for at least 3 feature releases now, it would seem reasonable to conclude that they shouldn't be considered tech preview any more. The following seem due for making official: qt_finalize_project(), qt_add_translations(), QT_DEPLOY_SUPPORT. [LM]: This is intentional because more changes are planned.
      • [Fixed in QTBUG-113138]: Some pages are showing what appears to be license-related internal comments in the rendered output, typically like this:
        // Copyright (C) 2020 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
        

        These appear in at least the doc pages for qt_finalize_project() and qt_add_executable().

      • The doc page for qt_generate_deploy_app_script() has a note saying it is currently only supported on Windows and macOS, but the Description mentions things that are implemented for Linux. This seems contradictory.
      • [Fixed]: The Synopsis for qt_add_translations() contains:
        [RESOURCE_PREFIX [OUTPUT_TARGETS variable-name]]

        but it should be:

        [RESOURCE_PREFIX prefix]
        [OUTPUT_TARGETS variable-name]

        The SOURCES and INCLUDE_DIRECTORIES keywords are also mentioned in the Synopsis, but they have no further explanation. The Synopsis should also show both of these as accepting a list of items, as should LUPDATE_OPTIONS and LRELEASE_OPTIONS.

      • qt_deploy_translations() contains the following text with a typo:
        For debugging purposed, the VERBOSE argument can be set to turn on diagnostic messages.
        

        The typo is purposed, which should be purposes.

      • The example for the QT_DEPLOY_SCRIPT variable doesn't actually use that variable, and is therefore not helpful in understanding how the variable is intended to be used. For comparison, the example in the QT_DEPLOY_TRANSLATIONS_DIR docs does mention QT_DEPLOY_SCRIPT and gives a better idea of how it should be used.

      It's probably also worth mentioning that the main example for qt_standard_project_setup() should use qt_generate_deploy_app_script() instead of the much more verbose and manual handling using qt_generate_deploy_script(). That particular example doesn't need to be as daunting as it currently looks to a new user. The example from qt_generate_deploy_app_script() would seem more appropriate for use in qt_standard_project_setup()'s docs.

      [Fixed the ones I could find]: It might also be worth a pass through all the Qt-provided CMake command docs to check if any examples still call add_executable() or add_library() instead of the recommended qt_add_executable() or qt_add_library() commands. The docs for qt_add_resources(), qt_wrap_cpp() and qt_wrap_ui() currently contain examples that call add_executable(), and there may be others.

      Attachments

        Issue Links

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

          Activity

            People

              leenam Leena Miettinen
              crscott Craig Scott
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: