forget *documenting* libiberty -- how about *installing* it?

[Geoff Keating]

Phil Edwards <pedwards@disaster.jaj.com> writes:

> I'm not concerned about the "makeup" functions like strncmp and friends;
> those should be declared by the user in one form or another.
> 
> But things like obstacks, hashtab, all of the x* functions, etc, should be
> declared only by including the proper header file, which the user would
> have to dig out of GCC sources and then hope that there's no mismatch
> between gcc/include/* and whatever installed libiberty.a is on the system.
> Or dig out all of libiberty and build a fresh version, Just In Case.

The original point of libiberty was that it's included with the
packages that use it.  It's intended to supply features like obstacks,
strncmp, and so on, that the GNU system provides (in glibc) but that
other systems might not.  I realize that it seems to have added
hashtables and the demangler and a few other things that aren't
present in glibc, but these are not the typical case.

One nice consequence of this is that it isn't necessary to document
all the functions that libiberty provides it its manual; you can just
refer to the functions' definitions in the glibc manual.

Another thing it does is provide wrappers around system functions,
like 'xmalloc'.  These do need documentation, but by definition should
not be installed anywhere standard as the wrappers may need to do
different things in different programs; interactive programs should
recover gracefully from malloc failing, for instance.  After all, if
they should be installed, then they should probably be provided by
glibc too.

-- 
- Geoffrey Keating <geoffk@geoffk.org>