samba-technical@lists.samba.org
[Top] [All Lists]

Re: [PATCH] Document talloc with doxygen

Subject: Re: [PATCH] Document talloc with doxygen
From: simo
Date: Fri, 29 Jan 2010 08:22:57 -0500
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"
> rather 
> than "what this function does". The upside is that the header remains
> cleaner, 
> 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
> headers 
> 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.

Simo.

-- 
Simo Sorce
Samba Team GPL Compliance Officer <simo@xxxxxxxxx>
Principal Software Engineer at Red Hat, Inc. <simo@xxxxxxxxxx>

<Prev in Thread] Current Thread [Next in Thread>