From f784714aea268248d17056320ac67d77c61eebe6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cristi=C3=A1n=20Maureira-Fredes?=
 <cristian.maureira-fredes@qt.io>
Date: Tue, 5 Jan 2021 11:12:21 +0100
Subject: QSetting.value add overload documentation

When the new overload to specify a new "type" parameter
was included, there was no documentation that could be reflected
in our API docs.

This adds a paragraph/example for the overload introduced by
78dad8180d797a647645b74255bfc29c46d7264a

Fixes: PYSIDE-1466
Change-Id: I843e650f8eb4c32f4c67a31ed5cf9047c4f171f9
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
(cherry picked from commit 9547dc918868470fe00fafe25d74a87b2ed35f1f)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
---
 .../PySide6/QtCore/typesystem_core_common.xml       | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

(limited to 'sources/pyside6')

diff --git a/sources/pyside6/PySide6/QtCore/typesystem_core_common.xml b/sources/pyside6/PySide6/QtCore/typesystem_core_common.xml
index 91d8c3e63..d0bb7ee32 100644
--- a/sources/pyside6/PySide6/QtCore/typesystem_core_common.xml
+++ b/sources/pyside6/PySide6/QtCore/typesystem_core_common.xml
@@ -2419,6 +2419,27 @@
     <modify-function signature="value(const QString&amp;,const QVariant&amp;)const" remove="all"/>
     <add-function signature="value(const QString&amp;, const QVariant&amp; @defaultValue@ = 0, PyObject* @type@ = 0)" return-type="PyObject*">
       <inject-code class="target" position="beginning" file="../glue/qtcore.cpp" snippet="qsettings-value"/>
+      <inject-documentation mode="append" format="target">
+        Custom overload that adds an optional named parameter to the function ``value()``
+        to automatically cast the type that is being returned by the function.
+
+        An example of this situation could be an ini file that contains
+        the value of a one-element list::
+
+            settings.setValue('var', ['a'])
+
+        The the ini file will be::
+
+            [General]
+            var=a  # we cannot know that this is a list!
+
+        Once we read it, we could specify if we want
+        the default behavior, a str, or to cast the output
+        to a list.
+
+            settings.value('var')  # Will get "a"
+            settings.value('var', type=list)  # Will get ["a"]
+      </inject-documentation>
     </add-function>
   </object-type>
   <object-type name="QEvent"  polymorphic-id-expression="%1-&gt;type() == QEvent::None">
-- 
cgit v1.2.3