[3.15] gh-87904: Document curses classes (GH-151643) (GH-152048)

Add docstrings for the curses.window, curses.error, curses.panel.panel
and curses.panel.error classes.  Document the panel class and its error
exception in curses.panel.rst, using the real lowercase panel name.
(cherry picked from commit 560ff8e)

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

Doc/library/curses.panel.rst

@@ -16,6 +16,14 @@ displayed.  Panels can be added, moved up or down in the stack, and removed.
 Functions
 ---------
 
+The module :mod:`!curses.panel` defines the following exception:
+
+
+.. exception:: error
+
+   Exception raised when a curses panel library function returns an error.
+
+
 The module :mod:`!curses.panel` defines the following functions:
 
 
@@ -48,73 +56,91 @@ The module :mod:`!curses.panel` defines the following functions:
 Panel objects
 -------------
 
-Panel objects, as returned by :func:`new_panel` above, are windows with a
-stacking order. There's always a window associated with a panel which determines
-the content, while the panel methods are responsible for the window's depth in
-the panel stack.
+.. raw:: html
+
+   <!-- Keep the old URL fragments working (see gh-89554) -->
+   <span id='curses.panel.Panel.above'></span>
+   <span id='curses.panel.Panel.below'></span>
+   <span id='curses.panel.Panel.bottom'></span>
+   <span id='curses.panel.Panel.hidden'></span>
+   <span id='curses.panel.Panel.hide'></span>
+   <span id='curses.panel.Panel.move'></span>
+   <span id='curses.panel.Panel.replace'></span>
+   <span id='curses.panel.Panel.set_userptr'></span>
+   <span id='curses.panel.Panel.show'></span>
+   <span id='curses.panel.Panel.top'></span>
+   <span id='curses.panel.Panel.userptr'></span>
+   <span id='curses.panel.Panel.window'></span>
+
+.. class:: panel
+
+   Panel objects, as returned by :func:`new_panel` above, are windows with a
+   stacking order.  There's always a window associated with a panel which
+   determines the content, while the panel methods are responsible for the
+   window's depth in the panel stack.
 
-Panel objects have the following methods:
+   Panel objects have the following methods:
 
 
-.. method:: Panel.above()
+.. method:: panel.above()
 
    Returns the panel above the current panel.
 
 
-.. method:: Panel.below()
+.. method:: panel.below()
 
    Returns the panel below the current panel.
 
 
-.. method:: Panel.bottom()
+.. method:: panel.bottom()
 
    Push the panel to the bottom of the stack.
 
 
-.. method:: Panel.hidden()
+.. method:: panel.hidden()
 
    Returns ``True`` if the panel is hidden (not visible), ``False`` otherwise.
 
 
-.. method:: Panel.hide()
+.. method:: panel.hide()
 
    Hide the panel. This does not delete the object, it just makes the window on
    screen invisible.
 
 
-.. method:: Panel.move(y, x)
+.. method:: panel.move(y, x)
 
    Move the panel to the screen coordinates ``(y, x)``.
 
 
-.. method:: Panel.replace(win)
+.. method:: panel.replace(win)
 
    Change the window associated with the panel to the window *win*.
 
 
-.. method:: Panel.set_userptr(obj)
+.. method:: panel.set_userptr(obj)
 
    Set the panel's user pointer to *obj*. This is used to associate an arbitrary
    piece of data with the panel, and can be any Python object.
 
 
-.. method:: Panel.show()
+.. method:: panel.show()
 
    Display the panel (which might have been hidden), placing it on top of
    the panel stack.
 
 
-.. method:: Panel.top()
+.. method:: panel.top()
 
    Push panel to the top of the stack.
 
 
-.. method:: Panel.userptr()
+.. method:: panel.userptr()
 
    Returns the user pointer for the panel.  This might be any Python object.
 
 
-.. method:: Panel.window()
+.. method:: panel.window()
 
    Returns the window object associated with the panel.
 

Modules/_curses_panel.c

@@ -672,7 +672,13 @@ static PyMethodDef PyCursesPanel_Methods[] = {
 
 /* -------------------------------------------------------*/
 
+PyDoc_STRVAR(PyCursesPanel_Type_doc,
+"A curses panel.\n"
+"\n"
+"Panel objects are returned by new_panel().");
+
 static PyType_Slot PyCursesPanel_Type_slots[] = {
+    {Py_tp_doc, (void *)PyCursesPanel_Type_doc},
     {Py_tp_clear, PyCursesPanel_Clear},
     {Py_tp_dealloc, PyCursesPanel_Dealloc},
     {Py_tp_traverse, PyCursesPanel_Traverse},
@@ -821,8 +827,10 @@ _curses_panel_exec(PyObject *mod)
     }
 
     /* For exception _curses_panel.error */
-    state->error = PyErr_NewException(
-        "_curses_panel.error", NULL, NULL);
+    state->error = PyErr_NewExceptionWithDoc(
+        "_curses_panel.error",
+        "Exception raised when a curses panel library function returns an error.",
+        NULL, NULL);
 
     if (PyModule_AddObjectRef(mod, "error", state->error) < 0) {
         return -1;

Modules/_cursesmodule.c

@@ -3099,7 +3099,14 @@ static PyGetSetDef PyCursesWindow_getsets[] = {
     {NULL, NULL, NULL, NULL }  /* sentinel */
 };
 
+PyDoc_STRVAR(PyCursesWindow_Type_doc,
+"A curses window.\n"
+"\n"
+"Window objects are returned by initscr() and newwin(), and by the\n"
+"methods that create subwindows and pads.");
+
 static PyType_Slot PyCursesWindow_Type_slots[] = {
+    {Py_tp_doc, (void *)PyCursesWindow_Type_doc},
     {Py_tp_methods, PyCursesWindow_methods},
     {Py_tp_getset, PyCursesWindow_getsets},
     {Py_tp_dealloc, PyCursesWindow_dealloc},
@@ -5560,7 +5567,10 @@ cursesmodule_exec(PyObject *module)
     }
 
     /* For exception curses.error */
-    state->error = PyErr_NewException("_curses.error", NULL, NULL);
+    state->error = PyErr_NewExceptionWithDoc(
+        "_curses.error",
+        "Exception raised when a curses library function returns an error.",
+        NULL, NULL);
     if (state->error == NULL) {
         return -1;
     }