gh-87881: Document the result of curses inch() and getbkgd() (GH-152488)

Explain the character/attribute bit layout and how to extract the parts
(A_CHARTEXT and A_ATTRIBUTES bit-masks, pair_number() for the color pair),
or use in_wch() to get a complexchar.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst
index 8d069ed8b7d1c4ace75038b1fa428fdb4eb8a6bf..f87ab7a8ee063ddcf71c0daf5b6051cad5e0542a 100644 (file)
--- a/Doc/library/curses.rst
+++ b/Doc/library/curses.rst
@@ -1332,6 +1332,7 @@ Window objects
 .. method:: window.getbkgd()
 
    Return the given window's current background character/attribute pair.
+   Its components can be extracted like those of :meth:`inch`.
    It cannot represent a background set with a wide character or with a color
    pair outside the :func:`color_pair` range; use :meth:`getbkgrnd` for those.
 
@@ -1486,11 +1487,13 @@ Window objects
 
 .. method:: window.inch([y, x])
 
-   Return the character at the given position in the window. The bottom 8 bits are
-   the character proper, and upper bits are the attributes.
+   Return the character at the given position in the window.
+   The bottom 8 bits are the character proper and the upper bits are the attributes;
+   extract them with the :data:`A_CHARTEXT` and :data:`A_ATTRIBUTES` bit-masks,
+   and the color pair with :func:`pair_number`.
    It cannot represent a cell holding combining characters, a character that does
    not fit in a single byte, or a color pair outside the :func:`color_pair`
-   range; use :meth:`in_wch` for those.
+   range; use :meth:`in_wch` for those, which returns it as a :class:`complexchar`.
 
 
 .. method:: window.in_wch([y, x])