|
|
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.
>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.
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?
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?
Cheers, Tridge
|
|