Fix testcase compilation with --disable-shared.

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

diff --git a/doc/man/libcdecl.3 b/doc/man/libcdecl.3
index 8bcc39440e18379056c4bd2cdd3f726a190dfe89..00280f5aae44d23528f46a6943b990c7f2b32f33 100644 (file)
--- a/doc/man/libcdecl.3
+++ b/doc/man/libcdecl.3
@@ -167,30 +167,46 @@ struct cdecl_declarator {
 };
 .Ed
 .Pp
 };
 .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
 .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
 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
 .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
 .Va child .
 .It Dv CDECL_DECL_IDENT    Ta Va ident        Ta Declares an identifier.  This

-declarator has no
+declarator has a NULL

 .Va child .
 .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
 .El
 .Ss Terminal Declarators
 Null and identifier declarators have no children and are thus leaf nodes.  A


@@ -257,6 +273,13 @@ each function parameter has exactly one full declarator (abstract or
 otherwise).   If
 .Va variadic
 is true, then the function is variadic.
 otherwise).   If
 .Va variadic
 is true, then the function is variadic.

+.Pp
+Note that old-style function declarations with non-empty identifier lists are
+not directly represented here: this is because they are syntactically identical
+to a prototype where every parameter is a typedef name.  Since
+.Nm
+isn't a C compiler, there is no way for the parser to tell these two kinds of
+declarations apart.

 .Sh ERROR HANDLING
 Some functions in
 .Nm
 .Sh ERROR HANDLING
 Some functions in
 .Nm