[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