Untangle the icon/name/description/categories mess

The documentation and the implementation disagreed quite heavily in
regards to the icon, name, description and categories fields in the
manifest for the package, each application and each intent.

The implementation now follows the existing documentation, but also
relaxing the requirements of icon and name being required for packages.

Also, it was confusing that applications could not override these
properties from the package like intents can do, so they also got
these properties.

Finally, everything is now correctly exposed to QML, with legacy
wrappers in place to not break old code.

In addition, the completely outdated applicationinfo unit-test
was rewritten to test all the current field combinations.

Change-Id: Ie5ad84bc6b771d6702b1994d1c8ae9f0204643b9
Pick-to: 6.3 6.3.0
Reviewed-by: Bernd Weimer <bernd.weimer@qt.io>
Reviewed-by: Dominik Holland <dominik.holland@qt.io>

2 files changed, 77 insertions, 10 deletions

diff --git a/doc/manifest.qdoc b/doc/manifest.qdoc
index db6ceb7d..113ec207 100644
--- a/doc/manifest.qdoc
+++ b/doc/manifest.qdoc
@@ -125,14 +125,15 @@ The fields within the \c info.yaml manifest data (second YAML document) are as f
     \li \c name
     \target package-name-map
     \li object
-    \li \e Required. An object containing language (\c string) to display name (\c string)
+    \li An optional object containing language (\c string) to display name (\c string)
         mappings. The language identifiers need to adhere to the standard POSIX locale definition.
-        For more information, see \l{QLocale}. At least one mapping needs to be present. However,
-        it is good practice to supply the English (\c en) mapping, at least, as a fallback.
+        For more information, see \l{QLocale}. It is good practice to supply at least the English
+        (\c en) mapping, as a fallback. If not supplying any mapping at all, the name will be the
+        same as the \c id.
 \row
     \li \c description
     \li object
-    \li \e An optional object containing language (\c string) to descriptive name (\c string)
+    \li An optional object containing language (\c string) to descriptive name (\c string)
         mappings. This field uses the same syntax as the \c name field.
 \row
     \li \c categories
@@ -256,6 +257,28 @@ The fields used for each item within the \c applications list are as follows:
     \li If provided, it is used as the automotive DLT application description, which allows to
         augment the short DLT application ID with a more verbose description. If not explicitly
         provided, a default description is used.
+\row
+    \li \c name
+    \li object
+    \li The name of the application. It will default to the \c name field in the global package
+        section, but it can be overwritten for each application by specifying this field.
+\row
+    \li \c icon
+    \li string
+    \li The icon of the application. It will default to the \c icon field in the global package
+        section, but it can be overwritten for each application by specifying this field.
+\row
+    \li \c description
+    \li object
+    \li The description of the application. It will default to the \c description field in the
+        global package section, but it can be overwritten for each application by specifying this
+        field.
+\row
+    \li \c categories
+    \li object
+    \li The list of categories for this application. It will default to the \c categories field in
+        the global package section, but it can be overwritten for each application by specifying
+        this field.
 \endtable
 
 \target manifest-intent
@@ -301,23 +324,23 @@ The fields used for each item within the \c intents list are as follows:
 \row
     \li \c name
     \li object
-    \li The name of the intent. It will default to the \c name field in the global section, but it
-        can be overridden for each intent by specifying this field.
+    \li The name of the intent. It will default to the \c name field in the global package section,
+        but it can be overwritten for each intent by specifying this field.
 \row
     \li \c icon
     \li string
-    \li The icon of the intent. It will default to the \c icon field in the global section, but it
-        can be overridden for each intent by specifying this field.
+    \li The icon of the intent. It will default to the \c icon field in the global package section,
+        but it can be overwritten for each intent by specifying this field.
 \row
     \li \c description
     \li object
     \li The description of the intent. It will default to the \c description field in the global
-        section, but it can be overridden for each intent by specifying this field.
+        package section, but it can be overwritten for each intent by specifying this field.
 \row
     \li \c categories
     \li object
     \li The list of categories for this intent. It will default to the \c categories field in the
-        global section, but it can be overridden for each intent by specifying this field.
+        global package section, but it can be overwritten for each intent by specifying this field.
 \endtable
 
 
diff --git a/doc/migration-guide-6.3.qdoc b/doc/migration-guide-6.3.qdoc
new file mode 100644
index 00000000..6d70211e
--- /dev/null
+++ b/doc/migration-guide-6.3.qdoc
@@ -0,0 +1,44 @@
+/****************************************************************************
+**
+** Copyright (C) 2022 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+
+\page migration-guide-6.3.html
+\ingroup qtappman
+\ingroup qtappman-highlights
+\title Migrating code from 6.2 to 6.3
+\brief Discusses factors for moving from the 6.2 to the 6.3 release of the Application Manager.
+
+Qt Application Manager 6.3 cleaned up the APIs and manifest definitions concerning the Package,
+Application and Intent fields for \c icon, \c name and \c description.
+All three support the same API now, with the package's fields acting as a fallback for both the
+application and intent objects.
+Due to a clash between the property \c name and the function \c name in ApplicationObject,
+user code that called the \c{Application.name(language)} function before, now needs to replace
+this with \c{Application.names[language]}.
+
+*/