2002-09-04  Theodore A. Roth  <address@hidden>

	* include/setjmp.h: Add dox comments.

Index: include/setjmp.h
===================================================================
RCS file: /cvsroot/avr-libc/avr-libc/include/setjmp.h,v
retrieving revision 1.1
diff -u -r1.1 setjmp.h
--- include/setjmp.h	5 Jul 2002 20:38:44 -0000	1.1
+++ include/setjmp.h	4 Sep 2002 05:39:51 -0000
@@ -63,11 +63,94 @@
 	unsigned char __j_pch;  /* only devices with >128K bytes of flash */
 } jmp_buf[1];
 
+/** \defgroup setjmp Setjmp and Longjmp
+
+    While the C language has the dreaded \c goto statement, it can only be
+    used to jump to a label in the same (local) function.  In order to jump
+    directly to another (non-local) function, the C library provides the
+    setjmp() and longjmp() functions.  setjmp() and longjmp() are useful for
+    dealing with errors and interrupts encountered in a low-level subroutine
+    of a program.
+
+    \note setjmp() and longjmp() make programs hard to understand and maintain.
+    If possible, an alternative should be used.
+
+    For a very detailed discussion of setjmp()/longjmp(), see Chapter 7 of
+    <em>Advanced Programming in the UNIX Environment</em>, by W. Richard
+    Stevens.
+
+    Example:
+
+    \code
+    #include <setjmp.h>
+
+    jmp_buf env;
+
+    int main (void)
+    {
+        if (setjmp (env))
+        {
+            ... handle error ...
+        }
+
+        while (1)
+        {
+           ... main processing loop which calls foo() some where ...
+        }
+    }
+
+    ...
+
+    void foo (void)
+    {
+        ... blah, blah, blah ...
+
+        if (err)
+        {
+            longjmp (env, 1);
+        }
+    }
+    \endcode */
+
 #ifndef __ATTR_NORETURN__
 #define __ATTR_NORETURN__ __attribute__((__noreturn__))
 #endif
 
+/** \ingroup setjmp
+    \brief Save stack context for non-local goto.
+
+    \code #include <setjmp.h>\endcode
+
+    setjmp() saves the stack context/environment in \e __jmpb for later use by
+    longjmp().  The stack context will be invalidated if the function which
+    called setjmp() returns.
+
+    \param __jmpb Variable of type \c jmp_buf which holds the stack
+    information such that the environment can be restored.
+
+    \returns setjmp() returns 0 if returning directly, and
+    non-zero when returning from longjmp() using the saved context. */
+
 extern int setjmp(jmp_buf __jmpb);
+
+/** \ingroup setjmp
+    \brief Non-local jump to a saved stack context.
+
+    \code #include <setjmp.h>\endcode
+
+    longjmp() restores the environment saved by the last call of setjmp() with
+    the corresponding \e __jmpb argument.  After longjmp() is completed,
+    program execution continues as if the corresponding call of setjmp() had
+    just returned the value \e __ret.
+
+    \note longjmp() cannot cause 0 to be returned.  If longjmp() is invoked
+    with a second argument of 0, 1 will be returned instead.
+
+    \param __jmpb Information saved by a previous call to setjmp().
+    \param __ret  Value to return to the caller of setjmp().
+
+    \returns This function never returns. */
+
 extern void longjmp(jmp_buf __jmpb, int __ret) __ATTR_NORETURN__;
 
 #endif  /* !__SETJMP_H_ */