Clarify the rule about structure typedefs being discouraged, following

a discussion on src-committers.

1 files changed, 12 insertions, 3 deletions

diff --git a/share/man/man9/style.9 b/share/man/man9/style.9
index a27e396..50fe3be 100644
--- a/share/man/man9/style.9
+++ b/share/man/man9/style.9
@@ -321,9 +321,18 @@ LIST_HEAD(, foo) foohead;		/* Head of global foo list. */
 .Ed
 .Pp
 Avoid using typedefs for structure types.
-This makes it impossible
-for applications to use pointers to such a structure opaquely, which
-is both possible and beneficial when using an ordinary struct tag.
+Typedefs are problematic because they do not properly hide their
+underlying type; for example you need to know if the typedef is
+the structure itself or a pointer to the structure.
+In addition they must be declared exactly once, whereas an
+incomplete structure type can be mentioned as many times as
+necessary.
+Typedefs are difficult to use in stand-alone header files:
+the header that defines the typedef must either be included
+before the header that uses it, or by the header that uses
+it (which causes namespace pollution), or there must be a
+back-door mechanism for obtaining the typedef.
+.Pp
 When convention requires a
 .Ic typedef ,
 make its name match the struct tag.