Why Samba development is hard

[Brad Hards]

On Friday 29 February 2008 04:55:54 am Kai Blin wrote:
> Problem 1: Documentation
> ------------------------
> Samba4 has some really nifty design ideas and a really cool technology
> behind it. However, if you haven't been around while all the pieces were
> designed and discussed, it's really hard to find out how to actually _do_
> things. Documentation seems to be in one of following states: outdated,
> wrong and nonexistent.
This is a hobby-horse of mine, so....

I don't have any real suggestions for nonexistent, but you can do automated 
checks for out-of-date Doxygen comments. KDE does a range of checks, 
including API documentation:
http://www.englishbreakfastnetwork.org/apidocs/index.php?component=kde-4.x
which allows you to "drill down" to get reports like:
http://www.englishbreakfastnetwork.org/apidocs/apidox-kde-4.x/kdelibs-kjs.html

The source code for that is available at:
http://websvn.kde.org/trunk/quality/apidox/

If Samba is serious about API documentation, perhaps there should be some kind 
of policy (even "please add API docs when you add new methods for ldb, talloc 
and tdb"). Although KDE focuses on C++ class docs, possibly something like 
the KDE one might be useful: 
http://techbase.kde.org/Policies/Library_Documentation_Policy

Of course, that doesn't get you any real design overview (which you can do in 
Doxygen, see  
http://api.kde.org/kdesupport-api/kdesupport-apidocs/qca/html/architecture.html 
for an example).  At some point you'll just have to read the code, but even 
pasting bits of email or IRC conversations into a Doxygen comment block might 
be useful to get started.

Brad