Re: Public methods description should be in header files

[Pascal Bourguignon]

> From: Richard Frith-Macdonald <address@hidden>
> Date: Mon, 14 Oct 2002 15:22:52 +0100
> 
> 
> On Monday, October 14, 2002, at 12:44  pm, Nicola Pero wrote:
> 
> >
> >> As I understand it you are basically saying that you want the
> >> source  of all documentation to be in header files and nowhere
> >> else, basically  because you like the ease of reading them in
> >> emacs, but also perhaps for  idealistic reasons of separation of
> >> interface and implementation, and conflation  of documentation
> >> with interface.
> >
> > Not all documentation has to be in headers ... all public
> > documentation has to be in headers; documentation about
> > implementation details and library internals is to be in sources.
> >
> > But yes - this is my main point - the headers declare the
> > available  public library API to the compilers and programmers
> > using it so it's most  natural to have the documentation about the
> > public library API there.
> 
> I think the purpose of header files is to declare interface to the
> compiler, and making human beings use them is fundamentally a little
> wrong, as it  is making the human conform to the needs of the
> machine.  Sure, programmers have to conform to the system all the
> time, but that's a necessary compromise, not a virtue.  Only habit
> makes it  seem natural - documentation is not the same thing as
> interface.  Pretty much all major software systems have separate
> documentation,  because most people find that easier than looking
> through source/headers.

No.  For a library, it's much  better to have the documentation in the
headers.

We're not  speaking about  an application and  the documentation  of a
user program that of course should not stays in the "sources".

Everytime I had  to use a library with a  separate documentation I had
big problems and  have had to revert to the headers  to solve them.  A
separate documentation is never as  precise, exact and up-to-date as a
header.

But that  said, usually the  headers lack precise  documentation about
the  general ways and  the general  features of  a library  (because a
header concerns only one class  or one module, not the whole library),
so yes, we need an  additionnal documentation too.  But it's better (I
would say  essential) to  have the documentation  of each unit  in its
interface file.


> However, I see that as a fairly minor point.  My concern is with
> getting people to write documentation ... not really an issue in
> your case since you  are very good at writing it.
> [...]


-- 
__Pascal_Bourguignon__                   http://www.informatimago.com/
----------------------------------------------------------------------
 The name is Baud,...... James Baud.