Clarify configuration loading precedence and YAML syntax

Change-Id: Ib0ba4da0b2b4bec53c1707d32bfe351e9789b0ba
Reviewed-by: Dominik Holland <dominik.holland@pelagicore.com>
Reviewed-by: Kavindra Palaraja <kpalaraja@luxoft.com>

3 files changed, 74 insertions, 5 deletions

diff --git a/doc/configuration.qdoc b/doc/configuration.qdoc
index 96f87163..28217c41 100644
--- a/doc/configuration.qdoc
+++ b/doc/configuration.qdoc
@@ -38,13 +38,26 @@ The currently supported command-line options can always be displayed by running
 Some of these options can also be set via config files, which in itself are referenced on the
 command-line with the \c{--config-file <filename>} option.
 
-The config file is a YAML file, consisting of exactly one object and it supports a subset of the
-command-line options.
+The config file is a \l {YAML syntax}{YAML file following the same rules} as all the other YAML
+files used in the application manager. Some of the options can only be set via the command line
+though.
 
 Any value that starts with the magic string \c ${CONFIG_PWD} will have this magic string replaced
 with the absolute path to the config file where it appears in - this makes it very easy to have
 all your imports paths and file references relative to your main config file.
 
+If an option is specified in more than one place: either on the command line and the config files,
+or across multiple config files, the final value is resolved based on these rules:
+\list
+\li Options are parsed from all the config files available, based on the order in which they appear
+    on the command line. Values are overridden by config files, as they are loaded.
+\li Options that are specified directly via the command line always override values in any config
+    file.
+\li There is one exception: options that expect a list of values, such as \c -I or \c ui/importPaths.
+    In this case, all values, regardless of where they are specified, will be merged into one
+    single, final list.
+\endlist
+
 \table
 \header
     \li Command Line \br \e {Config key}
@@ -458,7 +471,7 @@ dbus:
       startPackageInstallation:
         uids: [ 1000 ]
         capabilities: [ 'appstore' ]
-      acknowledgePackageInstallation: ~
+      acknowledgePackageInstallation: null
 ...
 \endcode
 
diff --git a/doc/manifest.qdoc b/doc/manifest.qdoc
index 4c919feb..a1e7896b 100644
--- a/doc/manifest.qdoc
+++ b/doc/manifest.qdoc
@@ -34,8 +34,8 @@
 
 \section1 Overview
 
-The package manifest or metadata file, \c info.yaml, is a YAML (version 1.1) file that consists of
-two YAML documents: the file-type header and the application manifest.
+The package manifest or metadata file, \c info.yaml, is a \l {YAML syntax}
+{YAML file following the same rules} as all the other YAML files used in the application manager.
 
 While the application manager can support other file formats, such as XML, currently the only
 metadata loader implemented is based on YAML.
diff --git a/doc/yaml.qdoc b/doc/yaml.qdoc
new file mode 100644
index 00000000..b87c5eaf
--- /dev/null
+++ b/doc/yaml.qdoc
@@ -0,0 +1,56 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 Luxoft Sweden AB
+** Copyright (C) 2018 Pelagicore AG
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Luxoft Application Manager.
+**
+** $QT_BEGIN_LICENSE:FDL-QTAS$
+** Commercial License Usage
+** Licensees holding valid commercial Qt Automotive Suite 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 yaml.html
+\title YAML Syntax
+
+All YAML files used in the application manager are parsed using a YAML 1.1 compliant parser.
+You can find the official specification here: \l{https://yaml.org/spec/1.1}.
+\note Node anchors and aliases are not supported in the application manager.
+
+To help with backward compatibility, all configuration files consist of at least two YAML
+sub-documents, with the first one acting as a file header, for example:
+
+\badcode
+formatType: am-configuration
+formatVersion: 1
+---
+...
+\endcode
+
+The header always has exactly two fields:
+\list
+\li \c formatType specifies the type of document(s) that follow the \c --- end-of-document marker.
+\li \c formatVersion is an integer value starting at \c 1.
+\endlist
+
+See the corresponding type documentation for valid values for both fields.
+
+*/