[src/trunk]: src/share/man/man3 As per suggestions from mrg@, improve the lea...

[jruoho <jruoho%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/edabaa9d5ba6
branches:  trunk
changeset: 752605:edabaa9d5ba6
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Tue Mar 02 06:20:03 2010 +0000

description:
As per suggestions from mrg@, improve the lead paragraph and stress that
these macros are not recommended. Also remove the example as it feels a
little frivolous and takes too much space.

diffstat:

 share/man/man3/__UNCONST.3 |  39 ++++++++++++++++-----------------------
 1 files changed, 16 insertions(+), 23 deletions(-)

diffs (71 lines):

diff -r d2832283a37c -r edabaa9d5ba6 share/man/man3/__UNCONST.3
--- a/share/man/man3/__UNCONST.3        Tue Mar 02 05:59:56 2010 +0000
+++ b/share/man/man3/__UNCONST.3        Tue Mar 02 06:20:03 2010 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: __UNCONST.3,v 1.2 2010/03/01 15:30:47 wiz Exp $
+.\"    $NetBSD: __UNCONST.3,v 1.3 2010/03/02 06:20:03 jruoho Exp $
 .\"
 .\" Copyright (c) 2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -43,40 +43,31 @@
 The
 .Fn __UNCONST
 macro can be used to omit warnings produced by certain compilers when
-a pointer declared with the
+operating with pointers declared with the
+.Em const
+type qualifier in a context without such qualifier.
+Examples include passing a pointer declared with the
 .Em const
-type qualifier is being passed to a function without such qualifier.
+qualifier to a function without such qualifier,
+and variable assignment from a
+.Em const
+pointer to a non-const pointer.
 In the same vein, the
 .Fn __UNVOLATILE
-macro can be used to omit warnings related to the
+macro can be used to exclude warnings related to the
 .Em volatile
 type qualifier.
 .Sh IMPLEMENTATION NOTES
-Both macros are implemented by explicitly using
+These macros are implemented by explicitly using
 .Em unsigned long
 instead of
 .Em intptr_t ,
 a signed type guaranteed to hold a pointer.
-.Sh EXAMPLES
-The following example demonstrates a possible usage of
-.Fn __UNCONST :
-.Bd -literal -offset indent
-const char *str = "/dev/null";
-
-api_function(__UNCONST(str));
-
-\&...
-
-static void
-api_function(char *str)
-{
-       \&...
-
-.Ed
 .Sh SEE ALSO
 .Xr cc 1
 .Sh CAVEATS
-Both macros should be used with care because these can hide valid errors.
+As both macros may hide valid errors, their usage is not recommended
+unless there is a well-thought reason for a cast.
 A typical use case for
 .Fn __UNCONST
 involve an
@@ -85,5 +76,7 @@
 even if it would be appropriate.
 Valid use cases of
 .Fn __UNVOLATILE
-include passing a volatile pointer to
+include passing a
+.Em volatile
+pointer to
 .Xr memset 3 .