Justin du Coeur (jducoeur) wrote,
Justin du Coeur

Open Source Documentation, and specifically Firefox

So we're now deeply immersed in the project of getting our fancy and powerful Browser Plugin working in Firefox. (Suffice it to say, we feed information from ASAP into the browser, so that the targeted webpages can have some features ranging from difficult to impossible otherwise.) The process is confirming all of my biases about Open Source.

On the one hand, the architecture of Mozilla is really rather nice. There are some silly decisions (like coming up with a new version of COM that is just different enough from Microsoft's as to be incompatible), but the overall notion of having the XUL+Javascript layer in control, and the C++ layer largely subordinate, seems both wise and rather innovative. A bit of a pain in the ass to work with for C++-centric apps like ours, but probably lovely in most cases.

That said: ohmigod, the documentation is such a mess. It's improving, and they're getting to the point where it's decent for conventional applets -- a tad scattershot and cryptic, but most of the information is there. But when you try to do something sophisticated, you're left with little choice but to dig into the source code (not exactly well-commented itself).

For example, right now I've got an unusual but straightforward problem. I want to have the Javascript on my page call into the C++ layer, passing in a Javascript callback to be invoked when we have an answer. Not that weird, right? After quite a lot of random digging through the source, I finally figured out that the answer is to use the "function" keyword in the IDL. Where is this documented? Nowhere, as far as I can tell. All of the online documentation for XPIDL points to the same document, with parenthetical comments that it is "a little out of date". Well, yeah -- it was last updated seven years ago! It's not even the "this is what we wrote" document, it's the "this is the spec for what we intend to write" document. Oy.

None of this is surprising, of course: open source projects are largely at the mercy of what the programmers want to do, and most programmers don't like writing documentation. But man -- it would all be so much more useful if there was a clear documentation plan here...
Tags: programming
  • Post a new comment


    Anonymous comments are disabled in this journal

    default userpic

    Your reply will be screened

    Your IP address will be recorded