[PATCH] Document talloc with doxygen

[Stefan (metze) Metzmacher]

tridge at samba.org schrieb:
> 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?

I have this:
[remote "gladiac"]
	url = git://gitorious.org/samba/gladiac-wip.git
	fetch = +refs/heads/*:refs/remotes/gladiac/*

and after a "git remote update"

git branch -a | grep gladiac
  gladiac/cmake
  gladiac/talloc
  gladiac/tevent
  gladiac/tsocket

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

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

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

Maybe this extra file gets included by doxygen or it includes the
doxygen stuff (maybe better, as we don't want to we site being included
in the generated manpage).

It would be nice if doxygen would generate just one large manpage
(I'm not sure if it already does that).

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/d7d830c6/attachment.pgp>