Help: Add option to only register highest versioned Qt documentation

In Options > Kits > Qt Versions. And make it the default.
It registers each documentation file only for the highest registered Qt
version. If you have Qt 5.12 and Qt 5.13 registered, but only installed
QtWebEngine for Qt 5.12, you'll get QtWebEngine documentation for Qt
5.12, but the other documentation is from Qt 5.13.
That is usually sufficient, since the documentation still contains "old"
API, and new API is flagged with "since".

This avoids registering a lot of documentation, which creates a startup
performance issue, and also leads to usually unneeded popups for which
Qt version some documentation should be shown.

The option also allows going back to registering all documentation,
and no Qt documentation at all.

Fixes: QTCREATORBUG-21482
Fixes: QTCREATORBUG-22799
Task-number: QTCREATORBUG-10004
Change-Id: I1c7bc73982d48d8e53f5083e2fa851b6c5f60f80
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Jarek Kobus <jaroslaw.kobus@qt.io>
Reviewed-by: Christian Stenger <christian.stenger@qt.io>
Reviewed-by: Eike Ziller <eike.ziller@qt.io>

doc/src/projects/creator-only/creator-projects-qt-versions.qdoc

@@ -80,6 +80,16 @@
 
         \endlist
 
+    \section1 Documentation
+
+    By default, \QC registers only the latest available version of the documentation for each
+    installed Qt module.
+
+    To register the documentation sets of all installed Qt versions, choose
+    \uicontrol{All} from the \uicontrol{Register documentation} list.
+    To register no Qt documentation at all, choose \uicontrol{None}.
+    The default behavior is \uicontrol{Highest Version Only}.
+
     \section1 Troubleshooting Qt Installations
 
     If \QC detects problems in the installation of a Qt version, it displays

src/plugins/help/helpmanager.cpp

@@ -196,6 +196,8 @@ void HelpManager::unregisterNamespaces(const QStringList &nameSpaces)
     bool docsChanged = false;
     for (const QString &nameSpace : nameSpaces) {
         const QString filePath = d->m_helpEngine->documentationFileName(nameSpace);
+        if (filePath.isEmpty()) // wasn't registered anyhow, ignore
+            continue;
         if (d->m_helpEngine->unregisterDocumentation(nameSpace)) {
             docsChanged = true;
             d->m_userRegisteredFiles.remove(filePath);

src/plugins/qtsupport/qtoptionspage.cpp

@@ -243,6 +243,16 @@ QtOptionsPageWidget::QtOptionsPageWidget(QWidget *parent)
     m_ui->qtdirList->setTextElideMode(Qt::ElideMiddle);
     m_ui->qtdirList->sortByColumn(0, Qt::AscendingOrder);
 
+    m_ui->documentationSetting->addItem(tr("Highest Version Only"),
+                                        int(QtVersionManager::DocumentationSetting::HighestOnly));
+    m_ui->documentationSetting->addItem(tr("All"), int(QtVersionManager::DocumentationSetting::All));
+    m_ui->documentationSetting->addItem(tr("None"),
+                                        int(QtVersionManager::DocumentationSetting::None));
+    const int selectedIndex = m_ui->documentationSetting->findData(
+        int(QtVersionManager::documentationSetting()));
+    if (selectedIndex >= 0)
+        m_ui->documentationSetting->setCurrentIndex(selectedIndex);
+
     QList<int> additions = transform(QtVersionManager::versions(), &BaseQtVersion::uniqueId);
 
     updateQtVersions(additions, QList<int>(), QList<int>());
@@ -756,19 +766,21 @@ void QtOptionsPageWidget::updateCurrentQtName()
 
 void QtOptionsPageWidget::apply()
 {
-    disconnect(QtVersionManager::instance(), &QtVersionManager::qtVersionsChanged,
+    disconnect(QtVersionManager::instance(),
-            this, &QtOptionsPageWidget::updateQtVersions);
+               &QtVersionManager::qtVersionsChanged,
+               this,
+               &QtOptionsPageWidget::updateQtVersions);
+
+    QtVersionManager::setDocumentationSetting(
+        QtVersionManager::DocumentationSetting(m_ui->documentationSetting->currentData().toInt()));
 
     QList<BaseQtVersion *> versions;
-
     m_model->forItemsAtLevel<2>([&versions](QtVersionItem *item) {
         item->setChanged(false);
         versions.append(item->version()->clone());
     });
-
     QtVersionManager::setNewQtVersions(versions);
 
-
     connect(QtVersionManager::instance(), &QtVersionManager::qtVersionsChanged,
             this, &QtOptionsPageWidget::updateQtVersions);
 }

src/plugins/qtsupport/qtversionmanager.cpp

@@ -67,6 +67,9 @@ const char QTVERSION_FILENAME[] = "/qtversion.xml";
 
 using VersionMap = QMap<int, BaseQtVersion *>;
 static VersionMap m_versions;
+
+const char DOCUMENTATION_SETTING_KEY[] = "QtSupport/DocumentationSetting";
+
 static int m_idcount = 0;
 // managed by QtProjectManagerPlugin
 static QtVersionManager *m_instance = nullptr;
@@ -95,9 +98,6 @@ bool qtVersionNumberCompare(BaseQtVersion *a, BaseQtVersion *b)
 static bool restoreQtVersions();
 static void findSystemQt();
 static void saveQtVersions();
-static void updateDocumentation(const QList<BaseQtVersion *> &added,
-                                const QList<BaseQtVersion *> &removed = {},
-                                const QList<BaseQtVersion *> &allNew = {});
 
 // --------------------------------------------------------------------------
 // QtVersionManager
@@ -145,7 +145,8 @@ void QtVersionManager::triggerQtVersionRestore()
                                      FileSystemWatcher::WatchModifiedDate);
     } // exists
 
-    updateDocumentation(m_versions.values());
+    const QList<BaseQtVersion *> vs = versions();
+    updateDocumentation(vs, {}, vs);
 }
 
 bool QtVersionManager::isLoaded()
@@ -464,37 +465,57 @@ void QtVersionManager::removeVersion(BaseQtVersion *version)
     delete version;
 }
 
-static QStringList documentationFiles(BaseQtVersion *v)
+using Path = QString;
+using FileName = QString;
+static QList<std::pair<Path, FileName>> documentationFiles(BaseQtVersion *v)
 {
-    QStringList files;
+    QList<std::pair<Path, FileName>> files;
     const QStringList docPaths = QStringList(
         {v->docsPath().toString() + QChar('/'), v->docsPath().toString() + "/qch/"});
     for (const QString &docPath : docPaths) {
         const QDir versionHelpDir(docPath);
         for (const QString &helpFile : versionHelpDir.entryList(QStringList("*.qch"), QDir::Files))
-            files.append(docPath + helpFile);
+            files.append({docPath, helpFile});
     }
     return files;
 }
 
-static QStringList documentationFiles(const QList<BaseQtVersion *> &vs)
+static QStringList documentationFiles(const QList<BaseQtVersion *> &vs, bool highestOnly = false)
 {
-    QStringList files;
+    QSet<QString> includedFileNames;
-    for (BaseQtVersion *v : vs)
+    QSet<QString> filePaths;
-        files += documentationFiles(v);
+    const QList<BaseQtVersion *> versions = highestOnly ? QtVersionManager::sortVersions(vs) : vs;
-    return files;
+    for (BaseQtVersion *v : versions) {
+        for (const std::pair<Path, FileName> &file : documentationFiles(v)) {
+            if (!highestOnly || !includedFileNames.contains(file.second)) {
+                filePaths.insert(file.first + file.second);
+                includedFileNames.insert(file.second);
+            }
+        }
+    }
+    return filePaths.values();
 }
-static void updateDocumentation(const QList<BaseQtVersion *> &added,
+
+void QtVersionManager::updateDocumentation(const QList<BaseQtVersion *> &added,
                                            const QList<BaseQtVersion *> &removed,
                                            const QList<BaseQtVersion *> &allNew)
 {
-    const QStringList docsOfAll = documentationFiles(allNew);
+    const DocumentationSetting setting = documentationSetting();
+    const QStringList docsOfAll = setting == DocumentationSetting::None
+                                      ? QStringList()
+                                      : documentationFiles(allNew,
+                                                           setting
+                                                               == DocumentationSetting::HighestOnly);
     const QStringList docsToRemove = Utils::filtered(documentationFiles(removed),
                                                      [&docsOfAll](const QString &f) {
                                                          return !docsOfAll.contains(f);
                                                      });
+    const QStringList docsToAdd = Utils::filtered(documentationFiles(added),
+                                                  [&docsOfAll](const QString &f) {
+                                                      return docsOfAll.contains(f);
+                                                  });
     Core::HelpManager::unregisterDocumentation(docsToRemove);
-    Core::HelpManager::registerDocumentation(documentationFiles(added));
+    Core::HelpManager::registerDocumentation(docsToAdd);
 }
 
 int QtVersionManager::getUniqueId()
@@ -613,4 +634,21 @@ void QtVersionManager::setNewQtVersions(const QList<BaseQtVersion *> &newVersion
         emit m_instance->qtVersionsChanged(addedIds, removedIds, changedIds);
 }
 
+void QtVersionManager::setDocumentationSetting(const QtVersionManager::DocumentationSetting &setting)
+{
+    if (setting == documentationSetting())
+        return;
+    Core::ICore::settings()->setValue(DOCUMENTATION_SETTING_KEY, int(setting));
+    // force re-evaluating which documentation should be registered
+    // by claiming that all are removed and re-added
+    const QList<BaseQtVersion *> vs = versions();
+    updateDocumentation(vs, vs, vs);
+}
+
+QtVersionManager::DocumentationSetting QtVersionManager::documentationSetting()
+{
+    return DocumentationSetting(
+        Core::ICore::settings()->value(DOCUMENTATION_SETTING_KEY, 0).toInt());
+}
+
 } // namespace QtVersion

src/plugins/qtsupport/qtversionmanager.h

@@ -69,11 +69,18 @@ signals:
     void qtVersionsLoaded();
 
 private:
+    enum class DocumentationSetting { HighestOnly, All, None };
+
+    static void updateDocumentation(const QList<BaseQtVersion *> &added,
+                                    const QList<BaseQtVersion *> &removed,
+                                    const QList<BaseQtVersion *> &allNew);
     void updateFromInstaller(bool emitSignal = true);
     void triggerQtVersionRestore();
 
     // Used by QtOptionsPage
     static void setNewQtVersions(const QList<BaseQtVersion *> &newVersions);
+    static void setDocumentationSetting(const DocumentationSetting &setting);
+    static DocumentationSetting documentationSetting();
     // Used by QtVersion
     static int getUniqueId();
 };

src/plugins/qtsupport/qtversionmanager.ui

@@ -26,6 +26,33 @@
      <item>
       <widget class="Utils::DetailsWidget" name="infoWidget" native="true"/>
      </item>
+     <item>
+      <layout class="QHBoxLayout" name="horizontalLayout2">
+       <item>
+        <widget class="QLabel" name="label">
+         <property name="text">
+          <string>Register documentation:</string>
+         </property>
+        </widget>
+       </item>
+       <item>
+        <widget class="QComboBox" name="documentationSetting"/>
+       </item>
+       <item>
+        <spacer name="horizontalSpacer">
+         <property name="orientation">
+          <enum>Qt::Horizontal</enum>
+         </property>
+         <property name="sizeHint" stdset="0">
+          <size>
+           <width>40</width>
+           <height>20</height>
+          </size>
+         </property>
+        </spacer>
+       </item>
+      </layout>
+     </item>
     </layout>
    </item>
    <item>