KWin Scripting API documentation [or fun with Qt and XML]

Martin Graesslin was kind enough to remind me of my responsibilities towards the software projects I participate in, most particulary “do NOT forget documentation”. So, I told him, that given 2 days, I’ll finish writing a small tutorial good enough to put devs on a starting track for KWin Scripting. However, as I sat down to write it out, it felt that the tutorial wouldn’t be as effective as it would be with nice API docs in place. So, for the first day of my grace, I began writing the API documentation for KWin Scripting.

IMPLIST although simple, wasn’t really easy-to-parse anymore. Plus I hadn’t provided enough documentation for the parameter lists, count and meanings over there. And without knowing more about arguments, scripting seemed impossible. So today I started out writing the documentation in a custom XML format and I kept on adding to the XML format as I proceeded. In the end I had covered quite an amount of documentation and the format seemed pretty portable and convenient to use. To save time, I also made use of some quick hacks.

The documentation in the XML format is available here. Then I wrote a small program to convert this XML file into a nice little formatted HTML file. I decided to use DOM over SAX, simply because it sounded easy for the task at my hand, however, now that I look at it, SAX could’ve been just as easy (or maybe, easier). The conversion program is *ugly*. And I mean it. There is a lot of code duplication, variable names I’ve completely lost track of and it’s overly unsystematic. But hey, it works, and does stuff under 4ms, so I’m happy . Plus I just wanted to get this API docs generated quickly, so I didn’t really care. Maybe, I’ll rewrite it sometime into something more extensible and elegant. The ugly abomination of code can be seen here.

And now, finally coming down to the docs, here you go. It’s just a listing for now, but I’ve added enough meta to add JavaScript filters and better navigation. Also, It’ll be available on techbase. Expect it soon. The tutorial should come tomorrow (I know I’ve said this before), but this time, I’m quite resolute (yes, I’ve said this also before).