No subject


Fri Jan 22 03:43:47 MST 2010


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


More information about the samba-technical mailing list