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

[Andrew Bartlett]

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
updated...

Andrew Bartlett

-- 
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
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.samba.org/archive/samba-technical/attachments/20060112/8d9f3dbb/attachment.bin