gh-86726: Fix and improve tkinter documentation and docstrings (GH-153549)

Correct inaccurate return-type and option descriptions in the tkinter
reference, and add missing module and class docstrings.
(cherry picked from commit 77cb756)

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 2 people

Doc/library/dialog.rst

@@ -175,19 +175,16 @@ specific value.
 
 .. class:: Open(master=None, **options)
            SaveAs(master=None, **options)
+           Directory(master=None, **options)
 
-   The above two classes provide native dialog windows for saving and loading
-   files.
+   The above three classes provide native dialog windows for loading and saving
+   files and for selecting a directory.
 
 **Convenience classes**
 
 The below classes are used for creating file/directory windows from scratch.
 These do not emulate the native look-and-feel of the platform.
 
-.. class:: Directory(master=None, **options)
-
-   Create a dialog prompting the user to select a directory.
-
 .. note::  The *FileDialog* class should be subclassed for custom event
    handling and behaviour.
 
@@ -311,23 +308,25 @@ the classic (non-themed) Tk widgets.
 
 .. data:: DIALOG_ICON
 
-   The name of the default bitmap (``'questhead'``) displayed by a
-   :class:`Dialog`.
+   The name of a bitmap (``'questhead'``) suitable for use as the *bitmap*
+   of a :class:`Dialog`.
 
 .. class:: Dialog(master=None, cnf={}, **kw)
 
    Display a modal dialog box built from the classic (non-themed) Tk widgets
    and wait for the user to press one of its buttons.
-   The options, given through *cnf* or as keyword arguments, include *title*
-   (the window title), *text* (the message), *bitmap* (an icon,
-   :data:`DIALOG_ICON` by default), *default* (the index of the default button)
-   and *strings* (the sequence of button labels).
+   The options, given through *cnf* or as keyword arguments, are all required:
+   *title* (the window title), *text* (the message), *bitmap* (the name of a
+   bitmap icon, such as :data:`DIALOG_ICON`), *default* (the index of the
+   default button) and *strings* (the sequence of button labels).
    After construction, the :attr:`!num` attribute holds the index of the button
    the user pressed.
 
    .. method:: destroy()
 
-      Destroy the dialog window.
+      Do nothing.
+      The dialog window is destroyed automatically before the constructor
+      returns, so there is nothing left for this method to do.
 
 
 .. seealso::

Doc/library/tkinter.messagebox.rst

@@ -13,9 +13,7 @@ a variety of convenience methods for commonly used configurations.
 The message boxes are modal: each blocks until the user responds, then returns
 a value that depends on the function.
 The ``show*`` functions and :meth:`Message.show` return the symbolic name of
-the button the user pressed, as a string (such as :data:`OK` or :data:`YES`),
-while the ``ask*`` functions return a :class:`bool` or ``None`` (see each
-function below).
+the button the user pressed, as a string (such as :data:`OK` or :data:`YES`).
 Common message box styles and layouts include but are not limited to:
 
 .. figure:: tk_msg.png

Doc/library/tkinter.rst

@@ -2280,8 +2280,8 @@ Base and mixin classes
       If all four arguments are given, the window manager keeps the ratio
       between ``minNumer/minDenom`` and ``maxNumer/maxDenom``; passing empty
       strings removes any existing restriction.
-      With no arguments, return a tuple of the four current values, or an empty
-      string if no aspect restriction is in effect.
+      With no arguments, return a tuple of the four current values, or ``None``
+      if no aspect restriction is in effect.
       :meth:`wm_aspect` is an alias of :meth:`!aspect`.
 
    .. method:: wm_attributes(*args, return_python_dict=False, **kwargs)
@@ -2506,8 +2506,8 @@ Base and mixin classes
       window's internally requested size, and *widthInc* and *heightInc* are
       the pixel sizes of a horizontal and vertical grid unit.
       Empty strings turn off gridded management.
-      With no arguments, return a tuple of the four current values, or an empty
-      string if the window is not gridded.
+      With no arguments, return a tuple of the four current values, or ``None``
+      if the window is not gridded.
       :meth:`wm_grid` is an alias of :meth:`!grid`.
 
       Not to be confused with the grid geometry manager :meth:`Grid.grid`.
@@ -2602,8 +2602,8 @@ Base and mixin classes
       Set or query a hint to the window manager about where the window's icon
       should be positioned.
       Empty strings cancel an existing hint.
-      With no arguments, return a tuple of the two current values, or an empty
-      string if no hint is in effect.
+      With no arguments, return a tuple of the two current values, or ``None``
+      if no hint is in effect.
       :meth:`wm_iconposition` is an alias of :meth:`!iconposition`.
 
    .. method:: wm_iconwindow(pathName=None)
@@ -2672,7 +2672,8 @@ Base and mixin classes
       When this flag is set, the window is ignored by the window manager: it is
       not reparented into a decorative frame and the user cannot manipulate it
       through the usual window manager controls.
-      With no argument, return a boolean indicating whether the flag is set.
+      With no argument, return a boolean indicating whether the flag is set,
+      or ``None`` if it has not been set.
       The flag is reliably honored only when the window is first mapped or
       remapped from the withdrawn state.
       :meth:`wm_overrideredirect` is an alias of :meth:`!overrideredirect`.

Doc/library/tkinter.ttk.rst

@@ -42,8 +42,9 @@ To override the basic Tk widgets, the import should follow the Tk import::
 
 That code causes several :mod:`!tkinter.ttk` widgets (:class:`Button`,
 :class:`Checkbutton`, :class:`Entry`, :class:`Frame`, :class:`Label`,
-:class:`LabelFrame`, :class:`Menubutton`, :class:`PanedWindow`,
-:class:`Radiobutton`, :class:`Scale` and :class:`Scrollbar`) to
+:class:`LabelFrame`, :class:`Menubutton`, :class:`OptionMenu`,
+:class:`PanedWindow`, :class:`Radiobutton`, :class:`Scale`,
+:class:`Scrollbar` and :class:`Spinbox`) to
 automatically replace the Tk widgets.
 
 This has the direct benefit of using the new widgets which gives a better look
@@ -1039,6 +1040,9 @@ ttk.Treeview
          The minimum width of the column in pixels. The treeview widget will
          not make the column any smaller than specified by this option when
          the widget is resized or the user drags a column.
+      *separator*: ``True``/``False``
+         Specifies whether a column separator should be drawn to the right of
+         the column.
       *stretch*: ``True``/``False``
          Specifies whether the column's width should be adjusted when
          the widget is resized.
@@ -1752,8 +1756,11 @@ and inherits the common methods of :class:`Widget`.
    display in the menu.
    A *command* keyword argument may be given to specify a callable that is
    invoked with the selected value whenever the selection changes; the *style*
-   keyword argument sets the style used by the underlying menubutton; and the
-   *name* keyword argument sets the Tk widget name.
+   keyword argument sets the style used by the underlying menubutton; the
+   *direction* keyword argument sets where the menu is posted relative to the
+   menubutton (one of ``'above'``, ``'below'`` (the default), ``'left'``,
+   ``'right'`` or ``'flush'``); and the *name* keyword argument sets the Tk
+   widget name.
 
    .. method:: set_menu(default=None, *values)
 

Lib/tkinter/__init__.py

@@ -3,7 +3,7 @@
 Tkinter provides classes which allow the display, positioning and
 control of widgets. Toplevel widgets are Tk and Toplevel. Other
 widgets are Frame, Label, Entry, Text, Canvas, Button, Radiobutton,
-Checkbutton, Scale, Listbox, Scrollbar, OptionMenu, Spinbox
+Checkbutton, Scale, Listbox, Scrollbar, OptionMenu, Spinbox,
 LabelFrame and PanedWindow.
 
 Properties of the widgets are specified with keyword arguments.
@@ -2436,7 +2436,7 @@ def wm_iconphoto(self, default=False, *args): # new in Tk 8.5
 
     def wm_iconposition(self, x=None, y=None):
         """Set the position of the icon of this widget to X and Y. Return
-        a tuple of the current values of X and X if None is given."""
+        a tuple of the current values of X and Y if None is given."""
         return self._getints(self.tk.call(
             'wm', 'iconposition', self._w, x, y))
 

Lib/tkinter/colorchooser.py

@@ -1,3 +1,5 @@
+"""Interface to the native Tk color selection dialog."""
+
 # tk common color chooser dialogue
 #
 # this module provides an interface to the native color dialogue

Lib/tkinter/commondialog.py

@@ -1,3 +1,5 @@
+"""Base class for the Tk common dialogs."""
+
 # base class for tk common dialogues
 #
 # this module provides a base class for accessing the common

Lib/tkinter/dialog.py

@@ -1,5 +1,7 @@
 # dialog.py -- Tkinter interface to the tk_dialog script.
 
+"""Classic Tk dialog box, wrapping the tk_dialog script."""
+
 from tkinter import _cnfmerge, Widget, TclError, Button, Pack
 
 __all__ = ["Dialog"]
@@ -8,6 +10,8 @@
 
 
 class Dialog(Widget):
+    """A modal dialog box built from the classic (non-themed) Tk widgets."""
+
     def __init__(self, master=None, cnf={}, **kw):
         cnf = _cnfmerge((cnf, kw))
         self.widgetName = '__dialog__'
@@ -21,7 +25,8 @@ def __init__(self, master=None, cnf={}, **kw):
         try: Widget.destroy(self)
         except TclError: pass
 
-    def destroy(self): pass
+    def destroy(self):
+        """Do nothing; the dialog window is already destroyed."""
 
 
 def _test():

Lib/tkinter/font.py

@@ -1,3 +1,5 @@
+"""Utilities to help work with fonts in Tkinter."""
+
 # Tkinter font wrapper
 #
 # written by Fredrik Lundh, February 1998

Lib/tkinter/messagebox.py

@@ -1,3 +1,5 @@
+"""Interface to the standard Tk message boxes."""
+
 # tk common message boxes
 #
 # this module provides an interface to the native message boxes