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

[simo]

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. 

I must confess I used primarily the html docs when programmed gtk/gnome
in the past, but that was because there were enough info there to do the
job. If we can document all our libs this way then I think the html docs
will be very valuable for external programmers that plan to use samba
libs. Developing the libs themselves is another matter.

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

understood.

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

ok, btw is it possible to split the docs to have a "user programmer"
functions and a section about the internal for ldb developers ?
In ldb_private.h we put functions that must not be used by client
programmers, they must be used only inside ldb (+modules) itself.

Simo.