Aerate the QgsSettings dox for readability

python/core/auto_generated/qgssettings.sip.in

@@ -15,12 +15,14 @@ class QgsSettings : QObject
 %Docstring
 
 This class is a composition of two QSettings instances:
+
 - the main QSettings instance is the standard User Settings and
 - the second one (Global Settings) is meant to provide read-only
 pre-configuration and defaults to the first one.
 
 For a given settings key, the function call to value(key, default) will return
 the first existing setting in the order specified below:
+
 - User Settings
 - Global Settings
 - Default Value
@@ -30,6 +32,7 @@ objects, with a static call to:
 static bool setGlobalSettingsPath( QString path );
 
 QgsSettings provides some shortcuts to get/set namespaced settings from/to a specific section:
+
 - Core
 - Gui
 - Server
@@ -39,7 +42,7 @@ QgsSettings provides some shortcuts to get/set namespaced settings from/to a spe
 - Providers
 - Misc
 
-.. versionadded:: 3
+.. versionadded:: 3.0
 %End
 
 %TypeHeaderCode
@@ -64,15 +67,16 @@ QgsSettings provides some shortcuts to get/set namespaced settings from/to a spe
     explicit QgsSettings( const QString &organization,
                           const QString &application = QString(), QObject *parent = 0 );
 %Docstring
-Construct a QgsSettings object for accessing settings of the application
+Constructs a QgsSettings object for accessing settings of the application
 called application from the organization called organization, and with parent parent.
 %End
 
     QgsSettings( QSettings::Scope scope, const QString &organization,
                  const QString &application = QString(), QObject *parent = 0 );
 %Docstring
-Construct a QgsSettings object for accessing settings of the application called application
+Constructs a QgsSettings object for accessing settings of the application called application
 from the organization called organization, and with parent parent.
+
 If scope is QSettings.UserScope, the QSettings object searches user-specific settings first,
 before it searches system-wide settings as a fallback. If scope is QSettings.SystemScope,
 the QSettings object ignores user-specific settings and provides access to system-wide settings.
@@ -87,11 +91,13 @@ locations.
     QgsSettings( QSettings::Format format, QSettings::Scope scope, const QString &organization,
                  const QString &application = QString(), QObject *parent = 0 );
 %Docstring
-Construct a QgsSettings object for accessing settings of the application called application
+Constructs a QgsSettings object for accessing settings of the application called application
 from the organization called organization, and with parent parent.
+
 If scope is QSettings.UserScope, the QSettings object searches user-specific settings first,
 before it searches system-wide settings as a fallback. If scope is QSettings.SystemScope,
 the QSettings object ignores user-specific settings and provides access to system-wide settings.
+
 If format is QSettings.NativeFormat, the native API is used for storing settings. If format
 is QSettings.IniFormat, the INI format is used.
 
@@ -101,7 +107,7 @@ locations.
 
     QgsSettings( const QString &fileName, QSettings::Format format, QObject *parent = 0 );
 %Docstring
-Construct a QgsSettings object for accessing the settings stored in the file called fileName,
+Constructs a QgsSettings object for accessing the settings stored in the file called fileName,
 with parent parent. If the file doesn't already exist, it is created.
 
 If format is QSettings.NativeFormat, the meaning of fileName depends on the platform. On Unix,
@@ -110,9 +116,12 @@ On Windows, fileName is a path in the system registry.
 
 If format is QSettings.IniFormat, fileName is the name of an INI file.
 
-Warning: This function is provided for convenience. It works well for accessing INI or .plist
-files generated by Qt, but might fail on some syntaxes found in such files originated by
-other programs. In particular, be aware of the following limitations:
+.. warning::
+
+   This function is provided for convenience. It works well for accessing INI or .plist
+   files generated by Qt, but might fail on some syntaxes found in such files originated by
+   other programs. In particular, be aware of the following limitations:
+
 - QgsSettings provides no way of reading INI "path" entries, i.e., entries with unescaped slash characters.
 (This is because these entries are ambiguous and cannot be resolved automatically.)
 - In INI files, QSettings uses the @ character as a metacharacter in some contexts, to encode

src/core/qgssettings.h

@@ -29,31 +29,34 @@
  * \class QgsSettings
  *
  * This class is a composition of two QSettings instances:
+ *
  * - the main QSettings instance is the standard User Settings and
  * - the second one (Global Settings) is meant to provide read-only
  *   pre-configuration and defaults to the first one.
  *
  * For a given settings key, the function call to value(key, default) will return
  * the first existing setting in the order specified below:
- *  - User Settings
- *  - Global Settings
- *  - Default Value
+ *
+ * - User Settings
+ * - Global Settings
+ * - Default Value
  *
  * The path to the Global Settings storage can be set before constructing the QgsSettings
  * objects, with a static call to:
  * static bool setGlobalSettingsPath( QString path );
  *
  * QgsSettings provides some shortcuts to get/set namespaced settings from/to a specific section:
- *  - Core
- *  - Gui
- *  - Server
- *  - Plugins
- *  - Auth
- *  - App
- *  - Providers
- *  - Misc
  *
- * \since QGIS 3
+ * - Core
+ * - Gui
+ * - Server
+ * - Plugins
+ * - Auth
+ * - App
+ * - Providers
+ * - Misc
+ *
+ * \since QGIS 3.0
  */
 class CORE_EXPORT QgsSettings : public QObject
 {
@@ -76,15 +79,16 @@ class CORE_EXPORT QgsSettings : public QObject
     };
 
     /**
-     * Construct a QgsSettings object for accessing settings of the application
+     * Constructs a QgsSettings object for accessing settings of the application
      * called application from the organization called organization, and with parent parent.
      */
     explicit QgsSettings( const QString &organization,
                           const QString &application = QString(), QObject *parent = nullptr );
 
     /**
-     * Construct a QgsSettings object for accessing settings of the application called application
+     * Constructs a QgsSettings object for accessing settings of the application called application
      * from the organization called organization, and with parent parent.
+     *
      * If scope is QSettings::UserScope, the QSettings object searches user-specific settings first,
      * before it searches system-wide settings as a fallback. If scope is QSettings::SystemScope,
      * the QSettings object ignores user-specific settings and provides access to system-wide settings.
@@ -99,11 +103,13 @@ class CORE_EXPORT QgsSettings : public QObject
                  const QString &application = QString(), QObject *parent = nullptr );
 
     /**
-     * Construct a QgsSettings object for accessing settings of the application called application
+     * Constructs a QgsSettings object for accessing settings of the application called application
      * from the organization called organization, and with parent parent.
+     *
      * If scope is QSettings::UserScope, the QSettings object searches user-specific settings first,
      * before it searches system-wide settings as a fallback. If scope is QSettings::SystemScope,
      * the QSettings object ignores user-specific settings and provides access to system-wide settings.
+     *
      * If format is QSettings::NativeFormat, the native API is used for storing settings. If format
      * is QSettings::IniFormat, the INI format is used.
      *
@@ -114,7 +120,7 @@ class CORE_EXPORT QgsSettings : public QObject
                  const QString &application = QString(), QObject *parent = nullptr );
 
     /**
-     * Construct a QgsSettings object for accessing the settings stored in the file called fileName,
+     * Constructs a QgsSettings object for accessing the settings stored in the file called fileName,
      * with parent parent. If the file doesn't already exist, it is created.
      *
      * If format is QSettings::NativeFormat, the meaning of fileName depends on the platform. On Unix,
@@ -123,14 +129,15 @@ class CORE_EXPORT QgsSettings : public QObject
      *
      * If format is QSettings::IniFormat, fileName is the name of an INI file.
      *
-     * Warning: This function is provided for convenience. It works well for accessing INI or .plist
+     * \warning This function is provided for convenience. It works well for accessing INI or .plist
      * files generated by Qt, but might fail on some syntaxes found in such files originated by
      * other programs. In particular, be aware of the following limitations:
-     *  - QgsSettings provides no way of reading INI "path" entries, i.e., entries with unescaped slash characters.
-     *    (This is because these entries are ambiguous and cannot be resolved automatically.)
-     *  - In INI files, QSettings uses the @ character as a metacharacter in some contexts, to encode
-     *     Qt-specific data types (e.g., \@Rect), and might therefore misinterpret it when it occurs
-     *     in pure INI files.
+     *
+     *    - QgsSettings provides no way of reading INI "path" entries, i.e., entries with unescaped slash characters.
+     *      (This is because these entries are ambiguous and cannot be resolved automatically.)
+     *    - In INI files, QSettings uses the @ character as a metacharacter in some contexts, to encode
+     *      Qt-specific data types (e.g., \@Rect), and might therefore misinterpret it when it occurs
+     *      in pure INI files.
      */
     QgsSettings( const QString &fileName, QSettings::Format format, QObject *parent = nullptr );