gh-86726: Document tkinter.simpledialog query options and Dialog.result (GH-151851)

diff --git a/Doc/library/dialog.rst b/Doc/library/dialog.rst
index 952fd1f0783671cd4417aa547f3d09ab1fd76583..402cfcfe75369f88e92750a707296ec3550e0e52 100644 (file)
--- a/Doc/library/dialog.rst
+++ b/Doc/library/dialog.rst
@@ -15,16 +15,31 @@ The :mod:`!tkinter.simpledialog` module contains convenience classes and
 functions for creating simple modal dialogs to get a value from the user.
 
 
-.. function:: askfloat(title, prompt, **kw)
-              askinteger(title, prompt, **kw)
-              askstring(title, prompt, **kw)
+.. function:: askfloat(title, prompt, *, initialvalue=None, minvalue=None, maxvalue=None, parent=None)
+              askinteger(title, prompt, *, initialvalue=None, minvalue=None, maxvalue=None, parent=None)
+              askstring(title, prompt, *, initialvalue=None, show=None, parent=None)
 
-   The above three functions provide dialogs that prompt the user to enter a value
-   of the desired type.
+   Prompt the user to enter a value of the desired type and return it, or
+   ``None`` if the dialog is cancelled.
+
+   *title* is the dialog title and *prompt* the message shown above the entry.
+   *initialvalue* is the value initially placed in the entry.
+   *parent* is the window over which the dialog is shown.
+   :func:`askinteger` and :func:`askfloat` also accept *minvalue* and
+   *maxvalue*, which bound the accepted value.
+   :func:`askstring` also accepts *show*, a character used to mask the entered
+   text, for example ``'*'`` to hide a password.
 
 .. class:: Dialog(parent, title=None)
 
    The base class for custom dialogs.
+   Instantiating it shows the dialog modally and returns once the user closes
+   it; the entered value is then available in the :attr:`!result` attribute.
+
+   .. attribute:: result
+
+      The value produced by :meth:`apply`, or ``None`` if the dialog was
+      cancelled.
 
    .. method:: body(master)
 
@@ -46,7 +61,8 @@ functions for creating simple modal dialogs to get a value from the user.
 
    .. method:: apply()
 
-      Process the data entered by the user.
+      Process the data entered by the user, for example by storing it in the
+      :attr:`!result` attribute.
       Called after :meth:`validate` succeeds and just before the dialog is
       destroyed.
       The default implementation does nothing; override it to act on or store