Further improvements to QgsProject dox

qgis · Oct 20, 2020 · 9f97955 · 9f97955
1 parent a259f50
commit 9f97955
Show file tree

Hide file tree

Showing 2 changed files with 129 additions and 46 deletions.
diff --git a/python/core/auto_generated/qgsproject.sip.in b/python/core/auto_generated/qgsproject.sip.in
@@ -409,7 +409,7 @@ Writes the project to its current associated file (see :py:func:`~QgsProject.fil
 
     bool writeEntry( const QString &scope, const QString &key, bool value ) /PyName=writeEntryBool/;
 %Docstring
-Write a boolean entry to the project file.
+Write a boolean ``value`` to the project file.
 
 Keys are '/'-delimited entries, implying
 a hierarchy of keys and corresponding values
@@ -421,11 +421,13 @@ a hierarchy of keys and corresponding values
 .. note::
 
    available in Python bindings as writeEntryBool
+
+.. seealso:: :py:func:`readBoolEntry`
 %End
 
     bool writeEntry( const QString &scope, const QString &key, double value ) /PyName=writeEntryDouble/;
 %Docstring
-Write a double entry to the project file.
+Write a double ``value`` to the project file.
 
 Keys are '/'-delimited entries, implying
 a hierarchy of keys and corresponding values
@@ -437,97 +439,123 @@ a hierarchy of keys and corresponding values
 .. note::
 
    available in Python bindings as writeEntryDouble
+
+.. seealso:: :py:func:`readDoubleEntry`
 %End
 
     bool writeEntry( const QString &scope, const QString &key, int value );
 %Docstring
-Write an integer entry to the project file.
+Write an integer ``value`` to the project file.
 
 Keys are '/'-delimited entries, implying
 a hierarchy of keys and corresponding values
 
 .. note::
 
    The key string must be valid xml tag names in order to be saved to the file.
+
+.. seealso:: :py:func:`readNumEntry`
 %End
 
     bool writeEntry( const QString &scope, const QString &key, const QString &value );
 %Docstring
-Write a string entry to the project file.
+Write a string ``value`` to the project file.
 
 Keys are '/'-delimited entries, implying
 a hierarchy of keys and corresponding values
 
 .. note::
 
    The key string must be valid xml tag names in order to be saved to the file.
+
+.. seealso:: :py:func:`readEntry`
 %End
 
     bool writeEntry( const QString &scope, const QString &key, const QStringList &value );
 %Docstring
-Write a string list entry to the project file.
+Write a string list ``value`` to the project file.
 
 Keys are '/'-delimited entries, implying
 a hierarchy of keys and corresponding values
 
 .. note::
 
    The key string must be valid xml tag names in order to be saved to the file.
+
+.. seealso:: :py:func:`readListEntry`
 %End
 
     QStringList readListEntry( const QString &scope, const QString &key, const QStringList &def = QStringList(), bool *ok /Out/ = 0 ) const;
 %Docstring
-Key value accessors
+Reads a string list from the specified ``scope`` and ``key``.
+
+:param scope: entry scope (group) name
+:param key: entry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
+:param def: default value to return if the specified ``key`` does not exist within the ``scope``.
 
-keys would be the familiar QgsSettings-like '/' delimited entries,
-implying a hierarchy of keys and corresponding values
+:return: - entry value as a string list
+         - ok: set to ``True`` if key exists and has been successfully retrieved as a string list
 %End
 
     QString readEntry( const QString &scope, const QString &key, const QString &def = QString(), bool *ok /Out/ = 0 ) const;
 %Docstring
+Reads a string from the specified ``scope`` and ``key``.
 
-:param def: returned value if key doesn't exist
+:param scope: entry scope (group) name
+:param key: entry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
+:param def: default value to return if the specified ``key`` does not exist within the ``scope``.
 
 :return: - entry value as string from ``scope`` given its ``key``
-         - ok: set to ``True`` if key exists and has been successfully retrieved
+         - ok: set to ``True`` if key exists and has been successfully retrieved as a string value
 %End
 
     int readNumEntry( const QString &scope, const QString &key, int def = 0, bool *ok /Out/ = 0 ) const;
 %Docstring
+Reads an integer from the specified ``scope`` and ``key``.
 
-:param def: returned value if key doesn't exist
+:param scope: entry scope (group) name
+:param key: entry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
+:param def: default value to return if the specified ``key`` does not exist within the ``scope``.
 
 :return: - entry value as integer from ``scope`` given its ``key``
-         - ok: set to ``True`` if key exists and has been successfully retrieved
+         - ok: set to ``True`` if key exists and has been successfully retrieved as an integer
 %End
 
     double readDoubleEntry( const QString &scope, const QString &key, double def = 0, bool *ok /Out/ = 0 ) const;
 %Docstring
+Reads a double from the specified ``scope`` and ``key``.
 
-:param def: returned value if key doesn't exist
+:param scope: entry scope (group) name
+:param key: entry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
+:param default: value to return if the specified ``key`` does not exist within the ``scope``.
 
 :return: - entry value as double from ``scope`` given its ``key``
-         - ok: set to ``True`` if key exists and has been successfully retrieved
+         - ok: set to ``True`` if key exists and has been successfully retrieved as a double
 %End
 
     bool readBoolEntry( const QString &scope, const QString &key, bool def = false, bool *ok /Out/ = 0 ) const;
 %Docstring
+Reads a boolean from the specified ``scope`` and ``key``.
 
-:param def: returned value if key doesn't exist
+:param scope: entry scope (group) name
+:param key: entry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
+:param default: value to return if the specified ``key`` does not exist within the ``scope``.
 
 :return: - entry value as boolean from ``scope`` given its ``key``
-         - ok: set to ``True`` if key exists and has been successfully retrieved
+         - ok: set to ``True`` if key exists and has been successfully retrieved as a boolean
 %End
 
     bool removeEntry( const QString &scope, const QString &key );
 %Docstring
-Remove the given key
+Remove the given ``key`` from the specified ``scope``.
 %End
 
-
     QStringList entryList( const QString &scope, const QString &key ) const;
 %Docstring
-Returns keys with values -- do not return keys that contain other keys
+Returns a list of child keys with values which exist within the the specified ``scope`` and ``key``.
+
+This method does not return keys that contain other keys. See :py:func:`~QgsProject.subkeyList` to retrieve keys
+which contain other keys.
 
 .. note::
 
@@ -536,7 +564,10 @@ Returns keys with values -- do not return keys that contain other keys
 
     QStringList subkeyList( const QString &scope, const QString &key ) const;
 %Docstring
-Returns keys with keys -- do not return keys that contain only values
+Returns a list of child keys which contain other keys that exist within the the specified ``scope`` and ``key``.
+
+This method only returns keys with keys, it will not return keys that contain only values. See
+:py:func:`~QgsProject.entryList` to retrieve keys with values.
 
 .. note::
 
@@ -545,6 +576,9 @@ Returns keys with keys -- do not return keys that contain only values
 
 
     void dumpProperties() const;
+%Docstring
+Dump out current project properties to stderr
+%End
 
     QgsPathResolver pathResolver() const;
 %Docstring
@@ -563,7 +597,7 @@ Paths written to the project file should be prepared with this method.
 
     QString readPath( const QString &filename ) const;
 %Docstring
-Turn filename read from the project file to an absolute path
+Transforms a ``filename`` read from the project file to an absolute path.
 %End
 
     QString error() const;
@@ -579,7 +613,9 @@ Deletes old handler and takes ownership of the new one.
 
     QString layerIsEmbedded( const QString &id ) const;
 %Docstring
-Returns project file path if layer is embedded from other project file. Returns empty string if layer is not embedded
+Returns the source project file path if the layer with matching ``id`` is embedded from other project file.
+
+Returns an empty string if the matching layer is not embedded.
 %End