[PATCH] Document talloc with doxygen

[Andreas Schneider]

On Friday 29 January 2010 03:20:05 tridge at samba.org wrote:
> Hi Andreas,

Hi Tridge,
 
> 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:

Thanks, I will improve the missing parts.
 
> Can you also tell me how I get a git clone of the source for this?

git clone git://gitorious.org/samba/gladiac-wip.git
git checkout -b talloc origin/talloc
 
> 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
> )

Yes, that's true. I've asked several developers if they prefer to have the 
code in the header file or in the source. They all think that it is the best 
to have it in the header file, cause if it is installed you have the full 
documentation and can read it in the header file. Handy if you don't have the 
doxygen files around and no internet link.

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

If you just have the header file and the library without the source you can 
use it, cause the documentation is in the header ...
 
> 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?

What do you mean exactly? doxygen has a C pre-processor it detects changes of 
arguments and function names.

How do you ensure talloc_guide.txt reflects the changes?

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

This is no problem. You can create a .dox file for the mainpage and for every 
other page you want, e.g. for a tutorial.

See http://dev.libssh.org/doxygen/tutorial.html


Cheers,

	-- andreas