On Mon, 27 Nov 2000, Sirtaj Singh Kang wrote:

> 
> On Sun, 26 Nov 2000, Peter Putzer wrote:
> [snip]
> > As for kdoc's stability and all, around 2.0 it didn't even RUN, though
> > that got fixed a week or so later. Unfortunately 2.0a42 didn't build
> > parameter lists, which kinda defeats the point of a doc-tool.

[snip]
 
> 2. The kdoc parser was too unwieldy to a) parse heavily templated code b)
> keep up with the preprocessor stuff that is appearing in KDE all the time,
> like k_dcop:, "Q_PROPERTY" or "EXPORTDOCKCLASS". I think most people will
> agree with me that just running the preprocessor, even though kdoc has
> supported this for a long time, is not really an option since a lot of
> context information (eg signals) gets lost.
> 
> So over the last few weeks I have totally rewritten the parser in kdoc,
> and through some absolutely godawful regexps it is now quite complete and
> extensible. It does not support everything 100% yet, but is finally able
> to take on new features without making eyes bleed.

I'm not quite convinced that Perl is the optimal language for parsing
context-free languages, but as that's what you've chosen...

> I've also added manpage support, proper (non-Polish!) latex support, and
> the docbook and HTML output will be changed quite heavily once the parser
> is complete, for example the HTML output will properly support stylesheets
> for customization using style classes for various parts of the docs.
> 
> I've also recently discovered that XML schemas exist for describing an OO
> API and adding support for that into kdoc is only a few hundred lines of
> code.

That sound's interesting for post-processing with other tools.

> Other stuff like multiple libdirs (ie hierarchical repositories for .kdoc
> files for kdevelop) have been implemented and removed from the wishlist.
> 
> Expect more in the next few weeks.
> 
> One thing that I will always try to do is make sure it atleast generates
> kdelibs docs properly before I make a commit (kdelibs has always been my
> primary test case), but I cannot fight stuff like EXPORTDOCKCLASS
> appearing without my knowing it.

Yes, that's very important, as generating documentation for kdelibs
probably kdoc's main use. Of course you're not at fault when someone
suddenly adds a new macro for header-directives, but the parser will
hopefully be robust enough spew out at least the basic stuff (parameters,
...) correctly.

cheers,
Peter