Re: Public methods description should be in header files

[Nicola Pero]

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

Ok - shall we then agree on this as a reasonable agreement ?

It would be nice to have all API documentation in a single place, but we
have not reached an agreement on where (headers vs source) to put it ...
at least not yet - so I'd say for now it's a reasonable agreement.



> > The downside is that it would likely generate duplicated documentation 
> > ...
> >
> > 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'm not sure - a little duplication might not be a big problem - but yes
in general I'd say we want to avoid duplications if possible.