[PATCH] assert.3: improved description

[Nikos Mavrogiannopoulos <nmav-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>]

Removed text referring to text not being helpful to users. Provide
the error text instead to allow the reader to determine whether it is helpful.
Recommend against using NDEBUG for programs to excibit deterministic behavior.
Moved description ahead of recommendations.

Signed-off-by: Nikos Mavrogiannopoulos <nmav-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
---
 man3/assert.3 | 29 +++++++++++++++--------------
 1 file changed, 15 insertions(+), 14 deletions(-)

diff --git a/man3/assert.3 b/man3/assert.3
index 7cf7328..1b85a68 100644
--- a/man3/assert.3
+++ b/man3/assert.3
@@ -24,6 +24,7 @@
 .\"
 .\" Modified Sat Jul 24 21:42:42 1993 by Rik Faith <faith-tsp8moGkja0@public.gmane.orgedu>
 .\" Modified Tue Oct 22 23:44:11 1996 by Eric S. Raymond <esr@thyrsus.com>
+.\" Modified Thu Jun  2 23:44:11 2016 by Nikos Mavrogiannopoulos <nmav-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
 .TH ASSERT 3  2015-08-08 "GNU" "Linux Programmer's Manual"
 .SH NAME
 assert \- abort the program if assertion is false
@@ -34,26 +35,26 @@ assert \- abort the program if assertion is false
 .BI "void assert(scalar " expression );
 .fi
 .SH DESCRIPTION
+This macro can help programmers find bugs in their programs, or handle exceptional cases
+via a crash that will produce limited debugging output. The function will print an
+error message to standard error, e.g., "assertion failed in file foo.c, function do_bar(), line 1287"
+and terminate the program by calling
+.BR abort (3)
+if
+.I expression
+is false (i.e., compares equal to zero).
+.LP
 If the macro
 .B NDEBUG
-was defined at the moment
+is defined at the moment
 .I <assert.h>
 was last included, the macro
 .BR assert ()
-generates no code, and hence does nothing at all.
-Otherwise, the macro
+generates no code, and hence does nothing at all. It is not recommended to define 
+.B NDEBUG
+if using
 .BR assert ()
-prints an error message to standard error and terminates the program
-by calling
-.BR abort (3)
-if
-.I expression
-is false (i.e., compares equal to zero).
-.LP
-The purpose of this macro is to help programmers find bugs in
-their programs.
-The message "assertion failed in file foo.c, function
-do_bar(), line 1287" is of no help at all to a user.
+to detect error conditions since the software may behave non-deterministically.
 .SH RETURN VALUE
 No value is returned.
 .SH ATTRIBUTES
-- 
2.5.5

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html