Re: Public methods description should be in header files

[Richard Frith-Macdonald]

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.

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.

> > I want to keep documentation primarily in source (but allowing 
> > headers) because
> > it's easier for me to write it there and I think that's true for 
> > others too, but
> > I would be quite happy to write stuff in the source and have you 
> > write stuff in
> > the headers ... makes no difference to me (or to autogsdoc generated
> > documentation).
>
> The downside is that it would likely generate duplicated documentation 
> ...
>
> has it already ?  NSDebug.m contains my original documentation of the
> GSDebugAlloc* functions (which I didn't put there but it's now there), 
> and
> I see you added new documentation for the same functions in NSDebug.h.

Sorry ... I will have moved that around a while back ... before I knew 
you
wanted to read your documentation in the header files.  I won't do that 
again.

> Not a great problem for now, but might become a problem as the
> documentation grows.

When I first thought about that, I was concerned ...  When I was first
thinking about generating documentation, I thought it would be nice to
provide simple comments in headers with more in-depth stuff in the
source code, but duplication was an obvious possibility -

My first thought was to generate a warning if this occurred.
My second was ... does it really matter if a little duplication occurs?

I concluded that the best thing to do was try it and see ... if it turns
out to be a real problem, the software could warn, or we could try other
solutions.