Re: public headers
On 2007-09-26 14:20, iesvs@free.fr wrote:
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).
I am not sure I quite understood the last part. Are you claiming that
keeping the documentation separate from the header files will
unavoidably result in lack of documentation? That is not true, a lack of
documentation is because lack of discipline and methodology.
By the way, I think that some of your problems comes from a C background
where a user of a library includes one header defining a few structs and
some functions that represent the whole interface to the library. In C++
it is more common with class libraries where each header provides only
one or a few classes, if more classes are required you have to include
some other header files. In C++ the interface to a library often is the
classes themselves.
--
Erik Wikstr??m