Depart from normal man page proactice a little and provide guidance on

when to use assert, as well as providing a bad example of using
assert.  While not strictly necessary, experience has shown issues
with poor assert choice happen often enough that this departure seems
warranted. Also, tighten up the previous example (there's no need
to have extra paragraphs or gratuitously long lines).

Reviewed by: emaste@ (earlier version)

share/man/man3/assert.3

@@ -28,7 +28,7 @@
 .\"     @(#)assert.3	8.1 (Berkeley) 6/9/93
 .\" $FreeBSD$
 .\"
-.Dd May 28, 2018
+.Dd May 31, 2018
 .Dt ASSERT 3
 .Os
 .Sh NAME
@@ -44,8 +44,7 @@ macro tests the given
 .Ar expression
 and if it is false,
 the calling process is terminated.
-A
-diagnostic message is written to
+A diagnostic message is written to
 .Dv stderr
 and the function
 .Xr abort 3
@@ -76,14 +75,26 @@ Each time whether or not
 is defined determines the behavior of assert from that point forward
 until the end of the unit or another include of
 .In assert.h .
+.Pp
+The
+.Fn assert
+macro should only be used for ensuring the developer's expectations
+hold true.
+It is not appropriate for regular run-time error detection.
 .Sh EXAMPLES
 The assertion:
-.Pp
 .Dl "assert(1 == 0);"
-.Pp
 generates a diagnostic message similar to the following:
+.Dl "Assertion failed: (1 == 0), function main, file main.c, line 100."
 .Pp
-.Dl "Assertion failed: (1 == 0), function main, file assertion.c, line 100."
+The following assert tries to assert there was no partial read:
+.Dl "assert(read(fd, buf, nbytes) == nbytes);"
+However, there are two problems.
+First, it checks for normal conditions, rather than conditions that
+indicate a bug.
+Second, the code will disappear if
+.Dv NDEBUG
+is defined, changing the semantics of the program.
 .Sh SEE ALSO
 .Xr abort2 2 ,
 .Xr abort 3