Try to fix explanations of "child" declarators in the manual.

[cdecl99.git] / doc / man / libcdecl.3

diff --git a/doc/man/libcdecl.3 b/doc/man/libcdecl.3
index a4dc5f45581fe9b85b7226411c5e9240dfd0f1a4..00280f5aae44d23528f46a6943b990c7f2b32f33 100644 (file)
--- a/doc/man/libcdecl.3
+++ b/doc/man/libcdecl.3
@@ -167,30 +167,46 @@ struct cdecl_declarator {
 };
 .Ed
 .Pp
-There are five types of declarators, distinguished by the
+With the exception of function parameters (which are handled separately),
+declarators form a chain from
+.Do outermost Dc to Do innermost Dc
+declarator.  This relationship is expressed by the
+.Va child
+struct member, which points to the next innermost declarator in the chain.
+Unfortunately, C's declaration syntax is, in a sense, inside-out.  Thus, one
+needs to follow the chain backwards (from innermost to outermost) to understand
+the semantic relationship between declarators in the chain.  In the next
+section, we will use the word
+.Va parent
+to describe this inverted child relationship: we consider the outermost
+declarator's
+.Va parent
+as the declaration's base type (found amongst the declaration specifiers, e.g.
+.Li int , const unsigned long ,
+etc.)
+
+The five types of declarators, described below, are distinguished by the
 .Va type
-struct member.  The union
-.u
+struct member.  Each declarator (except null declarators) carries additional
+information specific to its type, which corresponds to the members of the union
+.Va u .
+
 contains a member for each declarator type (except null) containing additional
-information.  The possible values are described by the following table.  The
-description of the child member is a lie.
+information.  The possible values are described by the following table.
 .Bl -column ".Dv CDECL_DECL_FUNCTION" ".Em Union Member"
 .It Em Declarator Type     Ta Em Union Member Ta Em Description
 .It Dv CDECL_DECL_NULL     Ta (none)          Ta Declares nothing.  This
-declarator has no
+declarator terminates the declarator chain, and has a NULL
 .Va child .
 .It Dv CDECL_DECL_IDENT    Ta Va ident        Ta Declares an identifier.  This
-declarator has no
+declarator has a NULL
 .Va child .
-.It Dv CDECL_DECL_POINTER  Ta Va pointer      Ta Declares a pointer.  The
-.Va child
-member is interpreted as "pointer to child".
-.It Dv CDECL_DECL_ARRAY    Ta Va array        Ta Declares an array.  The
-.Va child
-member is interpreted as "array of child".
-.It Dv CDECL_DECL_FUNCTION Ta Va function     Ta Declares a function.  The
-.Va child
-member is interpreted as "function returning child".
+.It Dv CDECL_DECL_POINTER  Ta Va pointer      Ta Declares a pointer, as in
+.Do pointer to Va parent Dc
+.It Dv CDECL_DECL_ARRAY    Ta Va array        Ta Declares an array, as in
+.Do array of Va parent Dc
+.It Dv CDECL_DECL_FUNCTION Ta Va function     Ta Declares a function, as in
+.Do function returning Va parent Dc
 .El
 .Ss Terminal Declarators
 Null and identifier declarators have no children and are thus leaf nodes.  A