[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Public methods description should be in header files

From: Nicola Pero
Subject: Re: Public methods description should be in header files
Date: Mon, 14 Oct 2002 15:46:33 +0100 (BST)

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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]