From 555ac45b20c299eb5c1efc9c6c76a757bccf4a7e Mon Sep 17 00:00:00 2001
From: "Andrew M. Kuchling" <amk@amk.ca>
Date: Mon, 31 Jul 2006 12:39:05 +0000
Subject: Document PyErr_WarnEx.  (Bad Neal!  No biscuit!)

Is the explanation of the 'stacklevel' parameter clear?  Please feel free
to edit it.

I don't have LaTeX installed on this machine, so haven't verified that the
markup is correct.  Will check tonight, or maybe the automatic doc build will
tell me.
---
 Doc/api/exceptions.tex | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/Doc/api/exceptions.tex b/Doc/api/exceptions.tex
index 504d1dc..8f5dc6c 100644
--- a/Doc/api/exceptions.tex
+++ b/Doc/api/exceptions.tex
@@ -259,10 +259,14 @@ for each thread.
   argument.  It is mostly for internal use.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyErr_Warn}{PyObject *category, char *message}
+\begin{cfuncdesc}{int}{PyErr_WarnEx}{PyObject *category, char *message, int stacklevel}
   Issue a warning message.  The \var{category} argument is a warning
   category (see below) or \NULL; the \var{message} argument is a
-  message string.
+  message string.  \var{stacklevel} is a positive number giving a
+  number of stack frames; the warning will be issued from the 
+  currently executing line of code in that stack frame.  A \var{stacklevel}
+  of 1 is the function calling \cfunction{PyErr_WarnEx()}, 2 is 
+  the function above that, and so forth.
 
   This function normally prints a warning message to \var{sys.stderr};
   however, it is also possible that the user has specified that
@@ -294,6 +298,16 @@ for each thread.
   command line documentation.  There is no C API for warning control.
 \end{cfuncdesc}
 
+\begin{cfuncdesc}{int}{PyErr_Warn}{PyObject *category, char *message}
+  Issue a warning message.  The \var{category} argument is a warning
+  category (see below) or \NULL; the \var{message} argument is a
+  message string.  The warning will appear to be issued from the function
+  calling \cfunction{PyErr_Warn()}, equivalent to calling
+  \cfunction{PyErr_Warn()} with a \var{stacklevel} of 1.
+  
+  Deprecated; use \cfunction{PyErr_WarnEx()} instead.
+\end{cfuncdesc}
+
 \begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category,
                 const char *message, const char *filename, int lineno,
                 const char *module, PyObject *registry}
-- 
cgit v0.12