Why Samba development is hard

[Kai Blin]

On Sunday 02 March 2008 10:03:29 Brad Hards wrote:

> 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.h
>tml
>
> The source code for that is available at:
> http://websvn.kde.org/trunk/quality/apidox/

It's a sad irony that the tools to make sure code is well-documented have a 
really crappy documentation.

Still, I like the system and will dig into that a bit, even though it's 
written in perl.

> 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

Yeah, we probably could put something like that into the wiki. Comments?

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

True. This week's going to be a bit crazy, but maybe I can look into this 
while on the train on Wednesday.

Cheers,
Kai

-- 
Kai Blin
WorldForge developer  http://www.worldforge.org/
Wine developer        http://wiki.winehq.org/KaiBlin
Samba team member     http://www.samba.org/samba/team/
--
Will code for cotton.
-------------- 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/20080303/d781bd60/attachment.bin