Port to use getline.h from dxcommon.

[cdecl99.git] / doc / libcdecl.3

diff --git a/doc/libcdecl.3 b/doc/libcdecl.3
index 022795acb173e5342cb2ed0d2ebbc9ca79e9e09e..725566b2944fa8bbfcf2b9dc02460b820e4a8672 100644 (file)
--- a/doc/libcdecl.3
+++ b/doc/libcdecl.3
@@ -1,4 +1,4 @@
-.Dd November 18, 2023
+.Dd January 17, 2024
 .Dt LIBCDECL \&3 "Cdecl99 Developer's Manual"
 .Os cdecl99
 .Sh NAME
@@ -17,7 +17,7 @@
 .Fd const struct cdecl_error *cdecl_get_error(void);
 .Pp
 .Fd int cdecl_spec_kind(struct cdecl_declspec *spec);
-.Fd bool cdecl_is_abstract(struct cdecl_declarator *declarator);
+.Fd int cdecl_is_abstract(struct cdecl_declarator *declarator);
 .Sh DESCRIPTION
 .Nm
 provides support for parsing C declarations and translating them to something
@@ -29,8 +29,7 @@ see the
 manual page.
 .Pp
 .Nm
-is intended to be portable to any system with a working C implementation that
-at least makes an effort to support C99.
+is intended to be portable to any system with a standard C compiler.
 The library is thread-safe when appropriate facilities exist and are enabled at
 build time.
 .Sh NAMESPACE
@@ -230,7 +229,7 @@ union member points to the C string containing the identifier.
 Since a null declarator may be deeply nested in the declarator chain, the
 function
 .Pp
-.Fd bool cdecl_is_abstract(struct cdecl_declarator *declarator);
+.Fd int cdecl_is_abstract(struct cdecl_declarator *declarator);
 .Pp
 can be used to determine whether or not a given declarator declares an
 identifier.
@@ -248,9 +247,10 @@ member is non-null, then it points to the first element of a singly-linked list
 of type qualifiers.
 .Ss Array Declarators
 .Bd -literal -offset indent
+typedef unsigned long long cdecl_uintmax; /* depends on configuration */
 struct cdecl_array {
        char *vla;
-       uintmax_t length;
+       cdecl_uintmax length;
 };
 .Ed
 .Pp
@@ -265,17 +265,32 @@ Otherwise, if
 .Va length
 is positive, then this is an array declarator with the specified length.
 Otherwise, this is an incomplete array declarator.
+.Pp
+If the library was configured using a compiler which does not support
+.Vt unsigned long long ,
+then the
+.Vt cdecl_uintmax
+type is defined as
+.Vt unsigned long
+instead.
+Prior versions of
+.Nm
+used
+.Vt uintmax_t
+directly.
 .Ss Function Declarators
 .Bd -literal -offset indent
+typedef _Bool cdecl_bool; /* depends on configuration */
 struct cdecl_function {
        struct cdecl *parameters;
-       _Bool variadic;
+       cdecl_bool variadic;
 };
 .Ed
 .Pp
 If
 .Va parameters
-is null, then this is a non-prototype function declarator.
+is null, then this is a non-prototype function declarator with an empty
+identifier list.
 Otherwise,
 .Va parameters
 points to the first element of a singly-linked list of declarations
@@ -284,15 +299,27 @@ Note that, unlike toplevel declarations, each function parameter has exactly
 one full declarator (abstract or otherwise).
 If
 .Va variadic
-is true, then the function is variadic.
+is non-zero, then the function is variadic.
+.Pp
+Please note that if the compiler used to build the library does not support
+.Vt _Bool ,
+then
+.Vt cdecl_bool
+will be defined as
+.Vt signed char
+instead.
+In most cases these will have a compatible binary representation, provided
+that applications do not set
+.Va variadic
+to any values besides 0 or 1.
 .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
+Old-style function declarations with non-empty identifier lists cannot be
+directly represented by this structure.
+Such declarations are syntactically identical to a prototype with every
+parameter consisting solely of a typedef name.
 .Nm
-isn't a C compiler, there is no way for its parser to tell these two kinds of
-declarations apart.
+cannot tell these apart when parsing and thus will return a parameter
+list, which can be rendered as expected.
 .Sh ERROR HANDLING
 Some functions in
 .Nm
@@ -425,7 +452,7 @@ is non-zero, the resulting string is '\\0' terminated even if it was truncated.
 .Sh AUTHORS
 Nick Bowler <nbowler@draconx.ca>
 .Sh COPYRIGHT
-Copyright \(co 2011\(en2012, 2021, 2023 Nick Bowler
+Copyright \(co 2011\(en2012, 2021, 2023\(en2024 Nick Bowler
 .Pp
 Permission is granted to copy, distribute and/or modify this manual under the
 terms of the GNU General Public License as published by the Free Software