On Fri, 2010-01-29 at 19:07 +1100, Brad Hards wrote:
> An alternative is to embed the documentation into the source (.c),
> which does
> have the risk in that you document "how the function does its stuff"
> than "what this function does". The upside is that the header remains
> and you don't have to recompile every dependency when you fix a typo
> in the API
> dox. That is obviously a good alternative if you're generating
> automatically (OpenChange does this).
One of the reasons it's in the header is that talloc's API and ABI
differ. Talloc heavily uses preprocessor macros in the header, and
that's the API you want to document.
Samba Team GPL Compliance Officer <simo@xxxxxxxxx>
Principal Software Engineer at Red Hat, Inc. <simo@xxxxxxxxxx>