[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-devel
Subject:    "Good" Docs [was: Re: accessing .desktop (.kdelnk) files]
From:       Kurt Granroth <granroth () alpha ! tat ! physik ! uni-tuebingen ! de>
Date:       1999-05-02 20:52:40
[Download RAW message or body]

David Faure wrote:
> > I think I am on the right track but the lack of documentation does
> > leave me guessing somewhat at the moment.
> About kmimetypes.h, I don't see how it could be more documented - Torben
> did the docu of all the methods, and I did the docu about the initialisation 
> stuff. (And under kdoc all this looks very nice !)

Good documentation goes *well* beyond documentation of class methods!
Class documentation as done with kdoc is very well suited to be used as
a reference.  In other words, they tell you what specific methods in a
specific class does.  If you are using that class, then such documentation
is invaluable.

HOWEVER, that only goes as far as that one class.  For simple stand-alone
classes (QString, KURLLabel, etc) that have little to no interaction with
other classes, this is all the documentation that is needed.  As soon as
the class becomes part of an overriding system, then this form of
documentation falls far short.

Let's take kmimetypes.h as an example.  The class therein is part of the
entire KDE mime/service/registry/whatever system.  It is virtually *useless*
by itself -- it's entire reason for being is soley in regards to its use
within the system.  That means that if the system *itself* is not
documented, then the class documentation for KMimeType might as well not
exist.

This isn't to say that some system-level documentation hasn't been started.
The design docs for Konqueror and kioslaves is a good start.. there just
isn't enough of that kind of stuff.

We are *seriously* lacking in design documentation for darn near everything
else, though.  How does all of the mime-stuff work together at a system
level?  Beats me.  Sure, I could spend a few hours digging through the
code and I could figure it out.. but I shouldn't have to.  If good docs
existed for the mime system, then the usage of the classes should be
obvious.

I think this lack of docs is mostly hurting us in the ultra-complex areas
such as KOffice and the "low-level" libs.  In both cases, the *only* people
that really know how they work is the people that develop on them on a day
to day basis (i.e., Reggie) OR developed them in the first place (i.e.,
Torben).  Because the amount of work necessary just to learn the system
(much less *extend* the system) is so huge, most people won't even touch it.

I've said it before and I'll likely say it many many more times: until we get
*good* design or system-level documentation on the complex portions of KDE,
there will only be at MOST a few people working on those systems!
-- 
Kurt Granroth            | granroth@kde.org
KDE Developer/Evangelist | http://www.pobox.com/~kurt_granroth

        KDE -- Putting a Friendly Face on Linux

[prev in list] [next in list] [prev in thread] [next in thread]