svn commit: samba r12850 - in branches/SAMBA_4_0/source/lib/ldb: . include

Andrew Bartlett abartlet at
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

Andrew Bartlett                      
Authentication Developer, Samba Team 
Student Network Administrator, Hawker College
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url :

More information about the samba-technical mailing list