[PATCH] Document talloc with doxygen

[simo]

On Fri, 2010-01-29 at 09:25 +0100, Stefan (metze) Metzmacher wrote:
> tridge at samba.org schrieb:
> >
> > 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. 
> >
> > 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.
> 
> why? I think it's really cool to have all documentation in the header file.

I agree, although the current form looks a bit ugly, I am sure we can
improve it.

> > 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?
> 
> As talloc.h contains a fixed api, changes won't happens that often
> and the person that changes it should check the doxygen output.

+1, we shouldn't change talloc headers enough to make this a real
concern.

> > 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?
> 
> Maybe we can put the website/html specific stuff into an extra file,
> but I like the rest being in the header.

I think we should leave any html out of the header file completely.
We will have whatever include file aside tied to our other website
stuff. Not only it is ugly to have ahtml in there, but we certainly want
to allow other people to rebuild the doxygen pages with their own stuff
if they like. Forcing some html on them would not be nice.

I think we shouldn't have it in git though, it looks *very* akward to
have commits in master about websites, we should keep anything website
related in the svn repository if at all possible, IMO.

Simo.

-- 
Simo Sorce
Samba Team GPL Compliance Officer <simo at samba.org>
Principal Software Engineer at Red Hat, Inc. <simo at redhat.com>