Re: Public methods description should be in header files

[Nicola Pero]

> 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 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.

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