http://samba.org/~vlendec/talloc-doc/index.html

[tridge at samba.org]

Hi Volker,

 > Under $SUBJECT you can find the output of doxygen run in
 > lib/talloc.

Thanks for putting that up. It is certainly a nice layout, but I'm not
sure that the content is actually better than what we have in
talloc_guide.txt.

For example, the doxygen generated function description of talloc() is
this:

 #define talloc ( ctx,
		type ) (type *)talloc_named_const(ctx, sizeof(type), #type)

whereas the one in talloc_guide.txt is this:

 (type *)talloc(const void *context, type);

The first one is technically correct, but is it useful? It is really
showing the internals of how the talloc() macro works, but it isn't a
nice description for someone who wants to know how to use it!

It is even worse for many of the other functions, which are described
in doxygen in terms of undocumented _talloc*() functions, which really
should not be exposed in documentation. The only reason the _talloc*()
functions exist as public functions is the fact that the way cpp works
requires it - they are supposed to be hidden from API users.

The talloc API has lots of these types of macro tricks, and some of
them have changed over the years. Even when the API itself has not
changed the description at the level that doxygen documents it has
often changed. I don't think we want that sort of internal change to
be part of the documentation.

Is it possible to override the function description in doxygen so we
can supply a more useful description than just reproducing the macro?

While reading through it I also noticed that both the doxygen and the
talloc_guide.txt docs have some out-dated stuff in them. For example,
the description of talloc_set_name_const() talks about its use in the
"auto-naming" functions like talloc_p(), whereas we moved to having
all of the talloc functions (or nearly all) be auto-naming a long time
ago, and we deprecated talloc_p(). I guess it's time to fix the
comments in those functions, and talloc_guide.txt.

Cheers, Tridge