svn commit: samba r12850 - in
branches/SAMBA_4_0/source/lib/ldb: . include
abartlet at samba.org
Thu Jan 12 12:14:24 GMT 2006
On Thu, 2006-01-12 at 21:48 +1100, Brad Hards wrote:
> On Thursday 12 January 2006 07:13 am, simo wrote:
> > On Thu, 2006-01-12 at 05:20 +1100, Brad Hards wrote:
> > > On Thursday 12 January 2006 03:40 am, simo wrote:
> > > > While I found the patch valuable I also found out that some code
> > > > becomes more difficult to be read, as an example, look at how
> > > > ldb_errors.h looks now, it is really much more difficult to quickly
> > > > list the error codes this way and spot the right one you should use.
> > > The problem is that if you change anything, you probably only update the
> > > docs if it is in your face. So I always try to keep it close.
> > You may be right. I'll give it a try.
> One thing that might be worth considering is whether the header file is your
> first reference when you have comprehensive annotated and cross-referenced
> HTML? If it is for you, do you expect it to be so for most programmers?
> Different projects do it different ways. The KDE experience is that a
> majority of developers mostly work from the generated docs (especially the Qt
> docs, which are very comprehensive). That may or may not apply to the ldb /
> samba community - I can't say.
Because of the poor state of Samba's developer documentation in the
past, the first reference is often whatever ctags brings up.
> > > > I was going to ask Brad if there is another way to add these comments
> > > > for example.
> > > But I can move the documentation, even to another file.
> > Would that compromise any functionality of doxygen ?
> Not at all. It wouldn't be as easy to write and it won't be anything like as
> easy to maintain, but it can be done.
I think the power of things like doxegen is keeping the documentation
with the source. There it at least stands some chance of being
Andrew Bartlett http://samba.org/~abartlet/
Authentication Developer, Samba Team http://samba.org
Student Network Administrator, Hawker College http://hawkerc.net
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.samba.org/archive/samba-technical/attachments/20060112/8d9f3dbb/attachment.bin
More information about the samba-technical