Re: Public methods description should be in header files

[Alexander Malmberg]

Nicola Pero wrote:
> 
> I feel we had this dicussion already, and you already knew I'm opposed to
> having public documentation in private .m files.

For what it's worth, I agree with Nicola here: I prefer to have public
documentation in the headers.

[snip]
> > 1. (This one I strongly believe myself) If the source comments for the
> > documentation are stored in the .m rather than the .h files, library 
> > developers
> > (working on the GNUstep code itself) are more likely to keep them up to
> > date.
> 
> Up to date ... ?  The API is not supposed to change.  Changing the
> implementation of a method in such a way that it behaves differently to
> the caller can have a lot of complicated and far reaching consequences for
> the gnustep-base or gnustep-gui libraries, so should be quite a rare
> event, and a lot of thought must be put into before doing it ... in those
> cases you should of course document the changes - but these cases
> are/should be the exceptions, not the rule.

Well, the current implementations of many things don't work as they're
"supposed" to work, so I don't think these changes will be that rare
(yet). IMHO, the documentation (preferably in the headers) should
document the intended behavior, and changing the implementation to match
that should be ok (even when it breaks things). This way, changing the
documentation should happen only rarely and after due consideration, and
"up-to-date" is meaningless.

- Alexander Malmberg