[PATCH] Document talloc with doxygen

Stefan (metze) Metzmacher metze at samba.org
Fri Jan 29 01:32:44 MST 2010


Brad Hards schrieb:
> On Friday 29 January 2010 13:20:05 tridge at samba.org wrote:
>> Once we get the above sorted out we will then need to work out how we
>> will keep the documentation up to date if/when the API changes, or we
>> wish to expand on the explanation of a function. 
> The best way to do this is probably to add a post-commit hook (or buildfarm 
> instance, if it supports this kind of thing) that regenerates the 
> documentation after each commit.
> 
>> From the web interface to the commits it looks like what you've done
>> is to embed the documentation and website in talloc.h (see
>> http://gitorious.org/samba/gladiac-wip/blobs/raw/talloc/lib/talloc/talloc.h
>> )
>>
>> It means that talloc.h becomes 95% documentation. I'll need to think
>> about whether that is really a good idea. It's nice to have the
>> documentation close to the code, but it also means that working with
>> the code becomes a rather strange experience.
> The way I look at it is that you now have a chance to figure out if you're 
> changing the declared behaviour when you change the header, and of course 
> makes it more likely that the documentation gets updated to reflect the new 
> API.  Also, if you're just reading the header, it makes it easier to figure out 
> what talloc_steal() (for example) might do.
> 
> 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".

Yes good point for keeping in the header:-)

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

I think public apis should have handwritten header files,
and the documentation should be in the header, it might be installed
into /usr/include/ and external users don't care about the .c files.

metze

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 260 bytes
Desc: OpenPGP digital signature
URL: <http://lists.samba.org/pipermail/samba-technical/attachments/20100129/59309299/attachment.pgp>


More information about the samba-technical mailing list