"protobuf_c_default_allocator" is the last bit of global data in
libprotobuf-c, and it can be hidden with some relatively easy (though
API/ABI-breaking) changes to ProtobufCBufferSimple.

all exported functions that take a ProtobufCAllocator either use the
provided allocator (if non-NULL), or switch to the default allocator (if
NULL). there are now two relatively unambiguous choices when a
ProtobufCAllocator is required by an exported function:

    1) use NULL. the vast majority of callers should pick this option.

    2) implement your own allocation functions, and enclose these in a
    ProtobufCAllocator struct.

in previous versions of protobuf-c there were two other possibilities:

    3) maybe use &protobuf_c_system_allocator?

    4) maybe use &protobuf_c_default_allocator?

this was relatively confusing, and by removing these latter two options
we can avoid having global library state.

most of the relevant material has now been updated and incorporated into
the doxygen documentation.

based heavily on kevin lyda's work in PR #140.

partially based on hunks split out of kevin lyda's PR #140.

this also significantly reorganizes the header file.

based heavily on kevin lyda's work in PR #140.

these identifiers aren't intended for use by client code. add a double
underscore to indicate this.

this identifier isn't intended for use by client code. add a double
underscore to indicate this.

these identifiers aren't intended for use by client code. add a double
underscore to indicate this.

offsetof() conforms to the C89 standard, just call it directly.

identifiers in any scope that begin with an underscore and a capital
letter are reserved in C.

these magic constants aren't intended for use by client code. add a
double underscore to indicate this.

assert() conforms to the C89 standard, just call it directly.

this macro isn't used anywhere except in the libprotobuf-c
implementation.

this avoids littering function definitions in the documentation with
"PROTOBUF_C_API".

identifiers that begin with an underscore are reserved. instead, use a
double underscore in the *middle* of the identifier to indicate that
it's an "internal" identifier.

identifiers that begin with a double underscore are reserved.

this is the unmodified output from "doxygen -l DoxygenLayout.xml".

this is the completely unmodified output output from running
"doxygen -g Doxyfile.in".  (note that this is doxygen 1.8.7.)

customization will come in a subsequent commit so that we have a record
of exactly what was changed from the default values.

exact version coupling between the compiler and the public headers is
too strict because some existing projects (such as collectd,
riemann-c-client, and nmsg) directly embed .pb-c.h files generated by
protoc-c into their exported headers. this would cause unnecessary build
failures in downstream clients of these libraries if a newer version of
the protobuf-c headers is installed.

however, it's still desireable to be able to explicitly declare when
compatibility is broken between the headers and the compiler, so
introduce new variables that allow independently setting the minimum
header version required by the compiler and the minimum compiler version
required by the header.

this follows the protobuf C++ implementation a little bit more closely,
though we don't have an analogous facility for verifying that the header
and *library* are compatible. (this seems like overkill for a C project;
in practice the headers and the library will be from the same version,
especially in downstream distributors like debian where the -dev package
has an exact versioned dependency on the shared library package.)

configure now has a "--enable-code-coverage" option, and if the
lcov/gcov tools are available a code coverage report can be built with
"make check-code-coverage".

this is mostly based on the AX_CODE_COVERAGE / GNOME_CODE_COVERAGE
macro:

    http://savannah.gnu.org/patch/?8451

but i also looked at knot-dns's code coverage implementation:

    https://github.com/CZNIC-Labs/knot/blob/master/m4/code-coverage.m4

and kevin lyda's pull request:

    https://github.com/protobuf-c/protobuf-c/pull/131/files