Documentation fixes

Added missing documentation and fixed warnings.
KDUpdate documentation not added in this commit.

Change-Id: Idc0b167bed95b7ae4a46a350290fdb241aa94448
Reviewed-by: Arttu Tarkiainen <arttu.tarkiainen@qt.io>

9 files changed, 124 insertions, 63 deletions

diff --git a/doc/scripting-api/gui.qdoc b/doc/scripting-api/gui.qdoc
index 35539c6be..53a8d20c2 100644
--- a/doc/scripting-api/gui.qdoc
+++ b/doc/scripting-api/gui.qdoc
@@ -177,7 +177,7 @@
 */
 
 /*!
-    \qmlmethod void gui::setTextItems(object control, string[] items)
+    \qmlmethod void gui::setTextItems(object control, stringlist items)
 
     Updates the model of \a control (which must be a QComboBox or QAbstractItemView)
     such that it contains the given \a items.
diff --git a/doc/scripting-api/packagemanagercore.qdoc b/doc/scripting-api/packagemanagercore.qdoc
index 8a31f54ea..f0bf1a19a 100644
--- a/doc/scripting-api/packagemanagercore.qdoc
+++ b/doc/scripting-api/packagemanagercore.qdoc
@@ -346,7 +346,7 @@
 */
 
 /*!
-   \qmlmethod void installer::setFileDialogAutomaticAnswer(string identifier, string &value)
+   \qmlmethod void installer::setFileDialogAutomaticAnswer(string identifier, string value)
 
     Automatically sets the existing directory or filename \a value to QFileDialog with the ID
    \a identifier.
@@ -363,6 +363,15 @@
 */
 
 /*!
+   \qmlmethod boolean installer::containsFileDialogAutomaticAnswer(string identifier)
+
+   Returns \c true if QFileDialog  with the ID \a identifier has an automatic answer set.
+
+   \sa setFileDialogAutomaticAnswer
+   \sa removeFileDialogAutomaticAnswer
+*/
+
+/*!
    \qmlmethod float installer::requiredDiskSpace()
 
    Returns the additional estimated amount of disk space in bytes required after installation.
@@ -553,6 +562,20 @@
 */
 
 /*!
+    \qmlmethod void installer::setAllowedRunningProcesses(stringlist processes)
+
+    Sets additional \a processes that can run when
+    updating with the maintenance tool.
+*/
+
+/*!
+    \qmlmethod stringlist installer::allowedRunningProcesses()
+
+    Returns processes that are allowed to run when updating with
+    the maintenance tool.
+*/
+
+/*!
     \qmlmethod void installer::setDependsOnLocalInstallerBinary()
 
     Makes sure the installer runs from a local drive. Otherwise the user will get an
@@ -822,6 +845,12 @@
 */
 
 /*!
+    \qmlmethod boolean installer::isCommandLineInstance()
+
+    Returns \c true if running as command line instance.
+*/
+
+/*!
     \qmlmethod boolean installer::runInstaller()
 
     Runs the installer. Returns \c true on success, \c false otherwise.
diff --git a/src/libs/installer/abstractfiletask.cpp b/src/libs/installer/abstractfiletask.cpp
index 83345db05..7e75ed9db 100644
--- a/src/libs/installer/abstractfiletask.cpp
+++ b/src/libs/installer/abstractfiletask.cpp
@@ -105,10 +105,12 @@ namespace QInstaller {
 */
 
 /*!
-    \fn FileTaskResult::FileTaskResult(const QString &t, const QByteArray &c, const FileTaskItem &i)
+    \fn FileTaskResult::FileTaskResult(const QString &t, const QByteArray &c,
+        const FileTaskItem &i, bool checksumMismatch)
 
     Creates file task results using the target file specified by \a t, checksum
-    specified by \a c, and file task item specified by \a i.
+    specified by \a c, file task item specified by \a i, and checksum mismatch
+    specified by \a checksumMismatch.
 */
 
 /*!
diff --git a/src/libs/installer/messageboxhandler.cpp b/src/libs/installer/messageboxhandler.cpp
index 2412cdf70..79630a54a 100644
--- a/src/libs/installer/messageboxhandler.cpp
+++ b/src/libs/installer/messageboxhandler.cpp
@@ -93,6 +93,8 @@ using namespace QInstaller;
             Accept the message box.
     \value  Reject
             Reject the message box.
+    \value  Default
+            Uses default answer set for message box.
 */
 
 /*!
diff --git a/src/libs/installer/packagemanagercore.cpp b/src/libs/installer/packagemanagercore.cpp
index 3a10c3ea3..137627ae1 100644
--- a/src/libs/installer/packagemanagercore.cpp
+++ b/src/libs/installer/packagemanagercore.cpp
@@ -407,7 +407,11 @@ using namespace QInstaller;
     Emitted when an unstable \a component is found containing an unstable \a type and \a errorMessage.
 */
 
+/*!
+    \fn PackageManagerCore::installerBinaryMarkerChanged(qint64 magicMarker)
 
+    Emitted when installer binary marker \a magicMarker has changed.
+*/
 
 Q_GLOBAL_STATIC(QMutex, globalModelMutex);
 static QFont *sVirtualComponentsFont = nullptr;
@@ -473,7 +477,6 @@ void PackageManagerCore::writeMaintenanceConfigFiles()
 
 /*!
     Disables writing of maintenance tool for the current session.
-    \sa {installer::disableWriteMaintenanceTool}{installer.disableWriteMaintenanceTool}
  */
 void PackageManagerCore::disableWriteMaintenanceTool(bool disable)
 {
@@ -637,7 +640,7 @@ void PackageManagerCore::setAutoAcceptLicenses()
 
    This can be used for unattended (automatic) installations.
 
-   \sa {installer::setFileDialogAutomaticAnswer){installer.setFileDialogAutomaticAnswer}
+   \sa {installer::setFileDialogAutomaticAnswer}{installer.setFileDialogAutomaticAnswer}
    \sa {QFileDialog::getExistingDirectory}{QFileDialog.getExistingDirectory}
    \sa {QFileDialog::getOpenFileName}{QFileDialog.getOpenFileName}
  */
@@ -650,7 +653,7 @@ void PackageManagerCore::setFileDialogAutomaticAnswer(const QString &identifier,
    Removes the automatic answer from QFileDialog with the ID \a identifier.
    QFileDialog can be called from script.
 
-   \sa {installer::removeFileDialogAutomaticAnswer){installer.removeFileDialogAutomaticAnswer}
+   \sa {installer::removeFileDialogAutomaticAnswer}{installer.removeFileDialogAutomaticAnswer}
    \sa {QFileDialog::getExistingDirectory}{QFileDialog.getExistingDirectory}
    \sa {QFileDialog::getOpenFileName}{QFileDialog.getOpenFileName}
  */
@@ -662,8 +665,8 @@ void PackageManagerCore::removeFileDialogAutomaticAnswer(const QString &identifi
 /*!
    Returns \c true if QFileDialog  with the ID \a identifier has an automatic answer set.
 
-   \sa {installer.containsFileDialogAutomaticAnswer}{installer::containsFileDialogAutomaticAnswer}
-   \sa {installer::removeFileDialogAutomaticAnswer){installer.removeFileDialogAutomaticAnswer}
+   \sa {installer::containsFileDialogAutomaticAnswer}{installer.containsFileDialogAutomaticAnswer}
+   \sa {installer::removeFileDialogAutomaticAnswer}{installer.removeFileDialogAutomaticAnswer}
    \sa {QFileDialog::getExistingDirectory}{QFileDialog.getExistingDirectory}
    \sa {QFileDialog::getOpenFileName}{QFileDialog.getOpenFileName}
  */
@@ -671,6 +674,7 @@ bool PackageManagerCore::containsFileDialogAutomaticAnswer(const QString &identi
 {
     return m_fileDialogAutomaticAnswers.contains(identifier);
 }
+
 /*!
  * Returns the hash of file dialog automatic answers
  * \sa setFileDialogAutomaticAnswer()
@@ -2163,6 +2167,12 @@ ComponentModel *PackageManagerCore::updaterComponentModel() const
     return d->m_updaterModel;
 }
 
+/*!
+    Lists available packages filtered with \a regexp without GUI. Virtual
+    components are not listed unless set visible.
+
+    \sa setVirtualComponentsVisible()
+*/
 void PackageManagerCore::listAvailablePackages(const QString &regexp)
 {
     qCDebug(QInstaller::lcInstallerInstallLog)
@@ -2178,7 +2188,7 @@ void PackageManagerCore::listAvailablePackages(const QString &regexp)
         const QString name = update->data(scName).toString();
         if (re.match(name).hasMatch() &&
                 (virtualComponentsVisible() ? true : !update->data(scVirtual, false).toBool())) {
-            printPackageInformation(name, update);
+            d->printPackageInformation(name, update);
             foundMatch = true;
         }
     }
@@ -2186,51 +2196,6 @@ void PackageManagerCore::listAvailablePackages(const QString &regexp)
         qCDebug(QInstaller::lcInstallerInstallLog) << "No matching packages found.";
 }
 
-void PackageManagerCore::printPackageInformation(const QString &name, const Package *update)
-{
-    qCDebug(QInstaller::lcPackageName).noquote() << "Id:" << name;
-    qCDebug(QInstaller::lcPackageDisplayname).noquote() << "\tDisplay name:" << update->data(scDisplayName).toString();
-    qCDebug(QInstaller::lcPackageVersion).noquote() << "\tVersion:" << update->data(scVersion).toString();
-    qCDebug(QInstaller::lcPackageDescription).noquote() << "\tDescription:" <<  update->data(scDescription).toString();
-    qCDebug(QInstaller::lcPackageReleasedate).noquote() << "\tRelease date:" << update->data(scReleaseDate).toString();
-    qCDebug(QInstaller::lcPackageDependencies).noquote() << "\tDependencies:" << update->data(scDependencies).toString();
-    qCDebug(QInstaller::lcPackageAutodependon).noquote() << "\tAutodependon:" << update->data(scAutoDependOn).toString();
-    qCDebug(QInstaller::lcPackageVirtual).noquote() << "\tVirtual:" << update->data(scVirtual, false).toString();
-    qCDebug(QInstaller::lcPackageSortingpriority).noquote() << "\tSorting priority:" << update->data(scSortingPriority).toString();
-    qCDebug(QInstaller::lcPackageScript).noquote() << "\tScript:" << update->data(scScript).toString();
-    qCDebug(QInstaller::lcPackageDefault).noquote() << "\tDefault:"<< update->data(scDefault, false).toString();
-    qCDebug(QInstaller::lcPackageEssential).noquote() << "\tEssential:" << update->data(scEssential, false).toString();
-    qCDebug(QInstaller::lcPackageForcedinstallation).noquote() << "\tForced installation:" << update->data(QLatin1String("ForcedInstallation"), false).toString();
-    qCDebug(QInstaller::lcPackageReplaces).noquote() << "\tReplaces:" << update->data(scReplaces).toString();
-    qCDebug(QInstaller::lcPackageDownloadableArchives).noquote() << "\tDownloadable archives:" << update->data(scDownloadableArchives).toString();
-    qCDebug(QInstaller::lcPackageRequiresAdminRights).noquote() << "\tRequires admin rights:" << update->data(scRequiresAdminRights).toString();
-    qCDebug(QInstaller::lcPackageCheckable).noquote() << "\tCheckable:" << update->data(scCheckable).toString();
-    qCDebug(QInstaller::lcPackageLicenses).noquote() << "\tLicenses:" << update->data(QLatin1String("Licenses")).toString();
-    qCDebug(QInstaller::lcPackageCompressedSize).noquote() << "\tCompressed size:" << update->data(QLatin1String("CompressedSize")).toString();
-    qCDebug(QInstaller::lcPackageUncompressedSize).noquote() << "\tUncompressed size:" << update->data(QLatin1String("UncompressedSize")).toString();
-
-    //Check if package already installed
-    LocalPackagesHash installedPackages = this->localInstalledPackages();
-    if (installedPackages.contains(name))
-        qCDebug(QInstaller::lcPackageInstalledVersion).noquote() << "\tInstalled version:" << installedPackages.value(name).version;
-}
-
-void PackageManagerCore::printLocalPackageInformation(const KDUpdater::LocalPackage package) const
-{
-    qCDebug(QInstaller::lcPackageName).noquote() << "Id:" << package.name;
-    qCDebug(QInstaller::lcPackageDisplayname).noquote() << "\tDisplay name:" << package.title;
-    qCDebug(QInstaller::lcPackageVersion).noquote() << "\tVersion:" << package.version;
-    qCDebug(QInstaller::lcPackageDescription).noquote() << "\tDescription:" <<  package.description;
-    qCDebug(QInstaller::lcPackageDependencies).noquote() << "\tDependencies:" << package.dependencies;
-    qCDebug(QInstaller::lcPackageAutodependon).noquote() << "\tAutodependon:" << package.autoDependencies;
-    qCDebug(QInstaller::lcPackageVirtual).noquote() << "\tVirtual:" << package.virtualComp;
-    qCDebug(QInstaller::lcPackageForcedinstallation).noquote() << "\tForced installation:" << package.forcedInstallation;
-    qCDebug(QInstaller::lcPackageCheckable).noquote() << "\tCheckable:" << package.checkable;
-    qCDebug(QInstaller::lcPackageUncompressedSize).noquote() << "\tUncompressed size:" << package.uncompressedSize;
-    qCDebug(QInstaller::lcPackageInstallDate).noquote() << "\tInstalled:" << package.installDate;
-    qCDebug(QInstaller::lcPackageUpdateDate).noquote() << "\tLast updated:" << package.lastUpdateDate;
-}
-
 bool PackageManagerCore::componentUninstallableFromCommandLine(const QString &componentName)
 {
     // We will do a recursive check for every child this component has.
@@ -2263,6 +2228,9 @@ bool PackageManagerCore::componentUninstallableFromCommandLine(const QString &co
     return true;
 }
 
+/*!
+    Lists installed packages without GUI.
+*/
 void PackageManagerCore::listInstalledPackages()
 {
     LocalPackagesHash installedPackages = this->localInstalledPackages();
@@ -2270,7 +2238,7 @@ void PackageManagerCore::listInstalledPackages()
     const QStringList &keys = installedPackages.keys();
     foreach (const QString &key, keys) {
         KDUpdater::LocalPackage package = installedPackages.value(key);
-        printLocalPackageInformation(package);
+        d->printLocalPackageInformation(package);
     }
 }
 
@@ -2344,6 +2312,11 @@ bool PackageManagerCore::updateComponentsSilently(const QStringList &componentsT
     return true;
 }
 
+/*!
+    Saves temporarily current operations for installer usage. This is needed
+    for unit tests when several commands (for example install and uninstall)
+    are performed with the same installer instance.
+*/
 void PackageManagerCore::commitSessionOperations()
 {
     d->commitSessionOperations();
@@ -2518,7 +2491,7 @@ void PackageManagerCore::dropAdminRights()
 }
 
 /*!
-    Sets checkAvailableSpace based on value of \c check.
+    Sets checkAvailableSpace based on value of \a check.
 */
 void PackageManagerCore::setCheckAvailableSpace(bool check)
 {
@@ -2527,8 +2500,8 @@ void PackageManagerCore::setCheckAvailableSpace(bool check)
 
 /*!
     Checks available disk space if the feature is not explicitly disabled. Informative
-    text about space status can be retrieved by passing \c message parameter. Returns
-    \a true if there is sufficient free space on installation and temporary volumes.
+    text about space status can be retrieved by passing \a message parameter. Returns
+    \c true if there is sufficient free space on installation and temporary volumes.
 */
 bool PackageManagerCore::checkAvailableSpace(QString &message) const
 {
@@ -2674,7 +2647,9 @@ bool PackageManagerCore::killProcess(const QString &absoluteFilePath) const
 
 /*!
     Sets additional \a processes that can run when
-    updating with the mainenance tool.
+    updating with the maintenance tool.
+
+    \sa {installer::setAllowedRunningProcesses}{installer.setAllowedRunningProcesses}
 */
 void PackageManagerCore::setAllowedRunningProcesses(const QStringList &processes)
 {
@@ -2684,6 +2659,8 @@ void PackageManagerCore::setAllowedRunningProcesses(const QStringList &processes
 /*!
     Returns processes that are allowed to run when
     updating with the maintenance tool.
+
+    \sa {installer::allowedRunningProcesses}{installer.allowedRunningProcesses}
 */
 QStringList PackageManagerCore::allowedRunningProcesses() const
 {
@@ -3256,6 +3233,8 @@ void PackageManagerCore::setCommandLineInstance(bool commandLineInstance)
 
 /*!
     Returns \c true if running as command line instance.
+
+    \sa {installer::isCommandLineInstance}{installer.isCommandLineInstance}
 */
 bool PackageManagerCore::isCommandLineInstance() const
 {
diff --git a/src/libs/installer/packagemanagercore.h b/src/libs/installer/packagemanagercore.h
index 87a14b93d..5b8f8cc1a 100644
--- a/src/libs/installer/packagemanagercore.h
+++ b/src/libs/installer/packagemanagercore.h
@@ -389,9 +389,6 @@ private:
     QList<Component *> componentsMarkedForInstallation() const;
 
     bool fetchPackagesTree(const PackagesList &packages, const LocalPackagesHash installedPackages);
-    void printPackageInformation(const QString &name, const Package *update);
-    void printLocalPackageInformation(const KDUpdater::LocalPackage package) const;
-
     bool componentUninstallableFromCommandLine(const QString &componentName);
 
 private:
diff --git a/src/libs/installer/packagemanagercore_p.cpp b/src/libs/installer/packagemanagercore_p.cpp
index ad4935abb..89be5d907 100644
--- a/src/libs/installer/packagemanagercore_p.cpp
+++ b/src/libs/installer/packagemanagercore_p.cpp
@@ -2613,5 +2613,49 @@ bool PackageManagerCorePrivate::askUserAcceptLicense(const QString &name, const
     }
 }
 
+void PackageManagerCorePrivate::printPackageInformation(const QString &name, const Package *update)
+{
+    qCDebug(QInstaller::lcPackageName).noquote() << "Id:" << name;
+    qCDebug(QInstaller::lcPackageDisplayname).noquote() << "\tDisplay name:" << update->data(scDisplayName).toString();
+    qCDebug(QInstaller::lcPackageVersion).noquote() << "\tVersion:" << update->data(scVersion).toString();
+    qCDebug(QInstaller::lcPackageDescription).noquote() << "\tDescription:" <<  update->data(scDescription).toString();
+    qCDebug(QInstaller::lcPackageReleasedate).noquote() << "\tRelease date:" << update->data(scReleaseDate).toString();
+    qCDebug(QInstaller::lcPackageDependencies).noquote() << "\tDependencies:" << update->data(scDependencies).toString();
+    qCDebug(QInstaller::lcPackageAutodependon).noquote() << "\tAutodependon:" << update->data(scAutoDependOn).toString();
+    qCDebug(QInstaller::lcPackageVirtual).noquote() << "\tVirtual:" << update->data(scVirtual, false).toString();
+    qCDebug(QInstaller::lcPackageSortingpriority).noquote() << "\tSorting priority:" << update->data(scSortingPriority).toString();
+    qCDebug(QInstaller::lcPackageScript).noquote() << "\tScript:" << update->data(scScript).toString();
+    qCDebug(QInstaller::lcPackageDefault).noquote() << "\tDefault:"<< update->data(scDefault, false).toString();
+    qCDebug(QInstaller::lcPackageEssential).noquote() << "\tEssential:" << update->data(scEssential, false).toString();
+    qCDebug(QInstaller::lcPackageForcedinstallation).noquote() << "\tForced installation:" << update->data(QLatin1String("ForcedInstallation"), false).toString();
+    qCDebug(QInstaller::lcPackageReplaces).noquote() << "\tReplaces:" << update->data(scReplaces).toString();
+    qCDebug(QInstaller::lcPackageDownloadableArchives).noquote() << "\tDownloadable archives:" << update->data(scDownloadableArchives).toString();
+    qCDebug(QInstaller::lcPackageRequiresAdminRights).noquote() << "\tRequires admin rights:" << update->data(scRequiresAdminRights).toString();
+    qCDebug(QInstaller::lcPackageCheckable).noquote() << "\tCheckable:" << update->data(scCheckable).toString();
+    qCDebug(QInstaller::lcPackageLicenses).noquote() << "\tLicenses:" << update->data(QLatin1String("Licenses")).toString();
+    qCDebug(QInstaller::lcPackageCompressedSize).noquote() << "\tCompressed size:" << update->data(QLatin1String("CompressedSize")).toString();
+    qCDebug(QInstaller::lcPackageUncompressedSize).noquote() << "\tUncompressed size:" << update->data(QLatin1String("UncompressedSize")).toString();
+
+    //Check if package already installed
+    LocalPackagesHash installedPackages = this->localInstalledPackages();
+    if (installedPackages.contains(name))
+        qCDebug(QInstaller::lcPackageInstalledVersion).noquote() << "\tInstalled version:" << installedPackages.value(name).version;
+}
+
+void PackageManagerCorePrivate::printLocalPackageInformation(const KDUpdater::LocalPackage package) const
+{
+    qCDebug(QInstaller::lcPackageName).noquote() << "Id:" << package.name;
+    qCDebug(QInstaller::lcPackageDisplayname).noquote() << "\tDisplay name:" << package.title;
+    qCDebug(QInstaller::lcPackageVersion).noquote() << "\tVersion:" << package.version;
+    qCDebug(QInstaller::lcPackageDescription).noquote() << "\tDescription:" <<  package.description;
+    qCDebug(QInstaller::lcPackageDependencies).noquote() << "\tDependencies:" << package.dependencies;
+    qCDebug(QInstaller::lcPackageAutodependon).noquote() << "\tAutodependon:" << package.autoDependencies;
+    qCDebug(QInstaller::lcPackageVirtual).noquote() << "\tVirtual:" << package.virtualComp;
+    qCDebug(QInstaller::lcPackageForcedinstallation).noquote() << "\tForced installation:" << package.forcedInstallation;
+    qCDebug(QInstaller::lcPackageCheckable).noquote() << "\tCheckable:" << package.checkable;
+    qCDebug(QInstaller::lcPackageUncompressedSize).noquote() << "\tUncompressed size:" << package.uncompressedSize;
+    qCDebug(QInstaller::lcPackageInstallDate).noquote() << "\tInstalled:" << package.installDate;
+    qCDebug(QInstaller::lcPackageUpdateDate).noquote() << "\tLast updated:" << package.lastUpdateDate;
+}
 
 } // namespace QInstaller
diff --git a/src/libs/installer/packagemanagercore_p.h b/src/libs/installer/packagemanagercore_p.h
index 0fe4ebd62..f78b52083 100644
--- a/src/libs/installer/packagemanagercore_p.h
+++ b/src/libs/installer/packagemanagercore_p.h
@@ -249,6 +249,8 @@ private:
     bool calculateComponentsAndRun();
     bool acceptLicenseAgreements() const;
     bool askUserAcceptLicense(const QString &name, const QString &content) const;
+    void printPackageInformation(const QString &name, const Package *update);
+    void printLocalPackageInformation(const KDUpdater::LocalPackage package) const;
 
 private:
     PackageManagerCore *m_core;
diff --git a/src/libs/installer/packagemanagergui.cpp b/src/libs/installer/packagemanagergui.cpp
index 229c68d4c..07b8bd369 100644
--- a/src/libs/installer/packagemanagergui.cpp
+++ b/src/libs/installer/packagemanagergui.cpp
@@ -1165,6 +1165,12 @@ void PackageManagerGui::currentPageChanged(int newId)
 */
 
 /*!
+    \fn PackageManagerPage::showOnPageListChanged()
+
+    Called when page visibility on page list has changed and refresh is needed.
+*/
+
+/*!
     \fn PackageManagerPage::leaving()
 
     Called when end users leave the page and the PackageManagerGui:currentPageChanged()