[PATCH 15/15] man/curs_get{_wch,ch}: Correct and clarify "RETURN VALUE" sections.

[G. Branden Robinson]

* Correct wgetch()'s return value; it doesn't return "OK", but a
  character code.
* Use the usual boilerplate for functions failing because a WINDOW
  pointer is null.
* Parallelize wording of sections between these pages where practical.
---
 man/curs_get_wch.3x | 21 +++++++++++----------
 man/curs_getch.3x   | 44 ++++++++++++++++++++++++++------------------
 2 files changed, 37 insertions(+), 28 deletions(-)

diff --git a/man/curs_get_wch.3x b/man/curs_get_wch.3x
index e58d326fb..f4cc6af76 100644
--- a/man/curs_get_wch.3x
+++ b/man/curs_get_wch.3x
@@ -173,18 +173,14 @@ .SH RETURN VALUE
 .B \%wget_wch
 returns
 .B OK
-when it reads a wide character and
+when it reads a wide character,
 .B \%KEY_CODE_YES
-when it reads a function key code.
-It returns
+when it reads a function key code,
+and
 .B ERR
-if
-.bP
-the
-.I \%WINDOW
-pointer is
-.BR NULL ","
-or
+on failure.
+.B \%wget_wch
+fails if
 .bP
 its timeout expires without any data arriving,
 or
@@ -195,6 +191,11 @@ .SH RETURN VALUE
 is set to
 .BR \%EINTR "."
 .PP
+Functions taking a
+.I \%WINDOW
+pointer argument fail if the pointer is
+.BR NULL "."
+.PP
 Functions prefixed with \*(``mv\*('' first perform cursor movement and
 fail if the position
 .RI ( y ,
diff --git a/man/curs_getch.3x b/man/curs_getch.3x
index a66e68a25..79b6d44f1 100644
--- a/man/curs_getch.3x
+++ b/man/curs_getch.3x
@@ -438,27 +438,18 @@ .SS "Testing Key Codes"
 See also
 \fB\%define_key\fP(3X) and \fB\%key_defined\fP(3X).
 .SH RETURN VALUE
-Except for
-.BR \%has_key ","
-these functions return
-.B OK
-on success and
+.B \%wgetch
+returns a key code identifying the key event as described above,
+which may include
+.B \%KEY_RESIZE
+or
+.B \%KEY_MOUSE
+indicating non-key events,
+or
 .B ERR
 on failure.
-.PP
-Functions taking a
-.I \%WINDOW
-pointer argument fail if the pointer is
-.BR NULL "."
-.PP
-Functions prefixed with \*(``mv\*('' first perform cursor movement and
-fail if the position
-.RI ( y ,
-.IR x ")"
-is outside the window boundaries.
-.PP
 .B \%wgetch
-also fails if
+fails if
 .bP
 its timeout expires without any data arriving,
 or
@@ -470,6 +461,12 @@ .SH RETURN VALUE
 .BR \%EINTR "."
 .PP
 .B \%ungetch
+returns
+.B OK
+on success and
+.B ERR
+on failure.
+.B \%ungetch
 fails if there is no more room in the input queue.
 .PP
 .B \%has_key
@@ -477,6 +474,17 @@ .SH RETURN VALUE
 .B TRUE
 or
 .BR FALSE "."
+.PP
+Functions taking a
+.I \%WINDOW
+pointer argument fail if the pointer is
+.BR NULL "."
+.PP
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x ")"
+is outside the window boundaries.
 .SH NOTES
 .BR \%getch ","
 .BR \%mvgetch ","
-- 
2.30.2

signature.asc
Description: PGP signature