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

Confusing omissions in docs about the QML Compiler

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Reported
    • Priority: P2: Important
    • Resolution: Unresolved
    • Affects Version/s: 5.15, 6.1.0
    • Fix Version/s: 6.3
    • Labels:
    • Platform/s:
      All

      Description

      I faced a few problems in docs for the QML Complier. I think it makes sense to fix them to ensure this feature is better accessible for the customers. Blow is the list. Most items are small and so I thought it is better post them in one issue. The below points refer to 6.1 but most of them are the same on the 5.15 space, unless otherwise noted. Links are not embedded for better readability.

      1. From the user perspective, QML Complier seems to have more than one name in the docs. It is listed as QML Disk Cache and as Qt Quick Compiler. This should either be unified, or explained to the user what is what and used accordingly.
      2. The landing page of Qt QML (https://doc.qt.io/qt-6/qtqml-index.html) lists QML Disk Cache (https://doc.qt.io/qt-6/qmldiskcache.html) under "Guides and Other Information" only. Despite the strange choice of the section, this is the only topic mentioned here. It is not clear why the user should know about QML Disk Cache w/o knowing what it is used for. Instead, other related topics are spread over other pages (see below)
      3. At the end of the of the content, the QML Cache page has a link to the "Qt Quick Compiler" (https://doc.qt.io/QtQuickCompiler) page which is the actual landing page for this domain. I believe it should be other way around.
      4. A side issue is that the same link to the Qt Quick Compiler page from the QML Disk Cache page in in Qt 5.15 lands in Archives (https://doc.qt.io/archives/QtQuickCompiler/) whereas on Qt 6.1 it lands to on the top-level bread crumps in https://doc.qt.io/QtQuickCompiler
      5. The Qt Quick Compiler page tells the user that qrc files are not needed anymore once this add-on has been used. Not sure if this is related to the current caching or the former compiler. This page might need some review...
      6. A search for "QML Compiler" in the search bar, reveals a few other related pages. Searching should not be required. We should collect all relevant page on one landing page
      7. The above search points to the page "Deploying QML Applications" (https://doc.qt.io/qt-6/qtquick-deployment.html) which then talks about "Ahead-of-Time Compilation" not mentioning the previous pages but repeating a part of their content. This space introduces the term of "cashing" which make people recall the QML Cache page whereas it is not directly mentioned there
      8. The same page, "Deploying QML Applications", provides a section "QML Caching" which is a bit repeating the content of the QML Disk Cache (https://doc.qt.io/qt-6/qmldiskcache.html) page.
      9. On the opposite, the Qt Quick Compiler does not mention the "caching" term and speaks of "byte code" which makes people think that the information in the QML Cache page is not relevant.
      10. The too qmlcachegen is not mentioned, neither document whereas mentioned on https://doc.qt.io/qt-6/configure-linux-device.html

        Attachments

          Issue Links

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

            Activity

              People

              Assignee:
              docteam Qt Documentation Team
              Reporter:
              vminenko Vladimir Minenko
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:

                  Gerrit Reviews

                  There are no open Gerrit changes