On Fri, Jan 14, 2011 at 4:09 PM, Robert Dewar <de...@adacore.com> wrote: > On 1/14/2011 8:47 AM, Achilleas Margaritis wrote: > >> 2) the actual knowledge about the program stored in a header is, from >> my rough estimation, up around 20% of what the program actually does. >> In order to incorporate the actual knowledge required, a lot of >> documentation has to be written. I comment my code with docified >> comments heavily in order to document every little detail of my >> program. This knowledge can never be deduced by the headers. The >> docified comments result in a nicely formatted documentation which is >> actually much easier to read than code in headers. > > The task of documenting specifications (what needs to be known > by clients) is radically different from documenting implementations > (what needs to be known by people fiddling with the implementation, > the client should NEVER need to look at the implementation, and > implementation details are not only irrelevant to the client, > but it is evil for the client to depend on them).
I never said anything about documenting the implementation. I am talking about documentation about the 'client' (I assume that you mean the programmers that will use a library or the programmers that will inherit the codebase). Documenting the implementation is done through comments in the implementation. It's totally irrelevant. I am talking about documenting the way an API is supposed to be used. > > That's the Ada philosophy in a nutshell, for Ada people, it is > the single most important feature of the language that it > encourages and to some extent mandates separation of spec > and implementation (I say to some extent, because I have > seen C folk writing Ada who regard the Ada specs as nuisance > headers and don't document them at all, which is a horrible > sin from an Ada perspective). > >> So, if the compiler checks the code, and the documentation says >> whatever must be said about the program, headers are completely >> redundant. > > But then you don't have proper documentation of the specification. Yes, you have: you run Doxygen (or your favorite doc extraction program) and you get nicely formatted and searchable HTML.
