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

List:       kde-devel
Subject:    kdoc (Re: Documentation standard ??)
From:       Sirtaj Singh Kang <ssk () physics ! unimelb ! edu ! au>
Date:       1999-07-07 16:45:34
[Download RAW message or body]

On Wed, 7 Jul 1999, Leon Widdershoven wrote:

> 
> Hi,
> 
> as far as I see, the "standard" is still kdoc. Of course,
> there are other possibilities, but some time ago it was 
> decided to go for kdoc. This was preferred above doxygen
> I think because of the signal/slot handling.

Here's some history:

-> DOC++ was the first program used, and a lot of documentation was
written with it by Kalle and others (incl me). 

-> Torben wrote a clever script called kdoc that did a lot of the same
stuff and also allowed linking with Qt docs.

-> I adopted this script because I was just starting seriously with perl
and rewrote it, giving kdoc 1.

-> I learned a lot about perl, and about how many different ways C++
programmers like to write code. :) Many features were requested for kdoc
1, and most of them were sensible.

-> I started on kdoc 2, a complete rewrite, with the idea of special
servicing of KDE documentation. This was and is my largest ever perl
program, and since then has grown a lot. 

The current status of kdoc is still "maintained", and it has gained many
features over the last year especially for KDE programmers, eg CORBA IDL
support (I believe it is the only free program that does a half-decent job
with this), better template support, auto-generation of full member lists
and re-implementation tracking, extended javadoc-style tags, nested
classes. It is still quite rough around the edges (as priorities for
features change), but I believe that no other program can be as quickly
adapted to KDE purposes with minimum coding. 

Every now and then someone would send me an email saying "kdoc is
obsolete, doxygen is better", but I stuck with kdoc development for a few
reasons; 1. ego (always the most important!) 2. the use of perl gives
maximum effect with minimum effort (important for all free software
projects) 3. I keep hoping that others will realize how easy it is to
extend kdoc's output facilities (Bernd Gehrmann is the only one so far)
and we will suddenly see a profusion of output formats for kdoc 4. I have
always generated the documentation for KDE on my devel site with kdoc, and
the thought of using a C++ program for it is not a good one (I had many
bad experiences with DOC++ and cocoon since the server was an RS/6000 and
is now an Alpha). 

In my mind so far is docbook, lxr and linuxdoc. A lot of my work in kdoc
so far has been to make it as modular as possible for this to happen, but
I admit I have not done such a good job of advertising this program so
far. When the bug list is reduced and the internal API is stable, this
will change.

Anyway, for more info about this program please see

http://www.ph.unimelb.edu.au/~ssk/kde/kdoc/

<end plug>

-Taj.

Sirtaj S. Kang       taj@kde.org         ssk@physics.unimelb.edu.au
Univ of Melbourne	
			"I'm a commercial operating system."
				-Doug Michels (CEO SCO)

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