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

Brad Hards bradh at frogmouth.net
Thu Jan 12 10:48:33 GMT 2006


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. 

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

> > > Plus some comments are wrong imho.
> > And incomplete. Please make lots of changes!
> I'll do while I spot them, thanks for the good work.
I also have some more changes, but not many yet. I'll send another patch when 
I have a few more things documented. I am also trying to do a diagram that 
shows the relationship between the data structures, but it is hard to figure 
out a good way to explain it.

Brad
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.samba.org/archive/samba-technical/attachments/20060112/46cd2a54/attachment.bin


More information about the samba-technical mailing list