> You really should not confuse the header files with the documentation of
> the API, they should be separate, even if it is just by generating the
> documentation from the source via doxygen or similar tools. Neither C
> not C++ is expressive enough to accurately describe an interface (such
> as pre- and post-conditions, invariants, etc.) with just the the
> information usually found in a header file.

Why not ? It's possible to describe a library with the headers. When
the developer make his library, he puts the information for the use in
comment of the header file.
I come from a language where looking the header files teach you
everything you need to use standard libraries.

And with your way of making libraries, we got this : you got a library
V2.0 but the API reference doesn't exist for the V1.0, and it's very
frequent (less currently the geeks have matured).