[PATCH] Document talloc with doxygen

[tridge at samba.org]

Hi Andreas,

Sorry for the slow response!

 > You can take a look at the html output at:
 >
 > http://www.cynapses.org/tmp/samba/talloc/

that layout is nice, thanks

 > I've integrated everything from the talloc homepage so that you can
 > replace the html file on talloc.samba.org with the documentation.

I don't think you have integrated all of the current information,
unless I've missed something. For example, in your html version the
description of talloc_free() function is here:

  http://www.cynapses.org/tmp/samba/talloc/group__talloc.html#ga7b536d1b6f8c95a206cb6a18bedf60fe

that description just says:

  ---------------------------------------------
  Free a chunk of talloc memory.

  Parameters:
      [in] 	ptr 	The chunk to be freed.

  Returns:
      0 on success, -1 on error. 
  ---------------------------------------------


on the current talloc.samba.org page the talloc API is described in
the ascii "talloc guide" here:

  http://samba.org/ftp/unpacked/talloc/talloc_guide.txt

in that guide we have quite a detailed description of talloc_free(),
under what conditions it can fail, what error messages it can produce
etc (see the text starting at line 113).

The same is true of talloc_steal() and some other functions.

I wonder if perhaps you used a old version of talloc_guide.txt in
building the html version?

Can you also tell me how I get a git clone of the source for this? I
haven't used gitorious before, and the web interface you referenced:

 > http://gitorious.org/samba/gladiac-wip/commits/talloc

doesn't seem to have a obvious link to a git URL. By clicking through
a few times I eventually got to
git://gitorious.org/samba/gladiac-wip.git, but a clone of that only
has a 'cmake' branch for all of Samba, and doesn't seem to contain the
documentation & web changes for talloc.

What's the magic incantation to get a git clone of this stuff from
gitorious?

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.