[PATCH] Document talloc with doxygen

[Brad Hards]

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". 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).
 
> If we did go with this, then how would a programmer working with
> talloc.h ensure that whatever changes pass the syntactic requirements
> of doxygen?
Running doxygen is the normal way (or a makefile equivalent). Buildfarm might 
also help, as noted previously.
KDE has a checker for this stuff, with a web API:
http://www.englishbreakfastnetwork.org/apidocs/apidox-kde-4.3/kdelibs-
kdecore.html

> I'm also not at all sure that having chunks of html in a .h file is a
> good idea. It looks like the stuff at the top of talloc.h is just raw
> html that is then used to build the talloc.samba.org web page. The
> talloc home page is pretty simple now, but if we want it to grow later
> we will want release announcements there, news links, tutorials, links
> to (for example) Rustys talk on talloc at LCA, and it seems a strange
> idea to be committing all those as comments in a C header file. How do
> you imagine we'd handle that?
You can add additional file types (I usually use .doxy as a suffix) that Doxygen 
will parse. You can move that to a doc/doxygen/ directory if you'd prefer 
(again, OpenChange uses this for some cases).

Brad