[PATCH 09/20] man/ncurses.3x: Revise "RETURN VALUE" section.

[G. Branden Robinson]

Reorganize to pull general rules about return values together in one
paragraph.

Tighten wording.

Drop discussion of function-like macros; this is covered in the "NOTES"
section and the C programmer is expected to understand that macros per
se do not "return" (whereas their textual expansions might).
---
 man/ncurses.3x | 29 ++++++++---------------------
 1 file changed, 8 insertions(+), 21 deletions(-)

diff --git a/man/ncurses.3x b/man/ncurses.3x
index 9767489bf..2bac6c66d 100644
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -946,35 +946,22 @@ .SS "Function Name Index"
 \fBcurs_trace\fP(3X) - curses debugging routines
 .RE
 .SH RETURN VALUE
-Routines that return an integer return \fBERR\fP upon failure and an
-integer value other than \fBERR\fP upon successful completion, unless
-otherwise noted in the routine descriptions.
-.PP
-As a general rule, routines check for null pointers passed as parameters,
-and handle this as an error.
-.PP
-All macros return the value of the \fBw\fP version, except \fBsetscrreg\fP,
-\fBwsetscrreg\fP, \fBgetyx\fP, \fBgetbegyx\fP, and \fBgetmaxyx\fP.
-The return values of
-\fBsetscrreg\fP,
-\fBwsetscrreg\fP,
-\fBgetyx\fP,
-\fBgetbegyx\fP, and
-\fBgetmaxyx\fP are undefined (i.e., these should not be used as the
-right-hand side of assignment statements).
+Unless otherwise noted,
+functions that return an integer return \fBOK\fP on success and
+\fBERR\fP on failure.
+Functions that return pointers return \fBNULL\fP on failure.
+Typically,
+.I \%ncurses
+treats a null pointer passed as a function parameter as a failure.
 .PP
 Functions with a \*(``mv\*('' prefix first perform cursor movement using
-\fB\%wmove\fP and return an error if the position is outside the window,
+\fB\%wmove\fP and fail if the position is outside the window,
 or
 (for \*(``mvw\*('' functions)
 if the
 .I \%WINDOW
 pointer is null.
-Most \*(``mv\*(''-prefixed functions
-(except variadic functions such as \fB\%mvprintw\fP)
-are provided both as macros and functions.
 .PP
-Routines that return pointers return \fBNULL\fP on error.
 .SH ENVIRONMENT
 The following environment symbols are useful for customizing the
 runtime behavior of the \fI\%ncurses\fP library.
-- 
2.30.2

signature.asc
Description: PGP signature