Generating Documentation With Dehydra

One of the common complaints about the Mozilla string code is that it’s very difficult to know what methods are available on a given class. Reading the code is very difficult because it’s hidden behind a complex set of #defines, it’s parameterized for both narrow and wide strings, and because we have a deep and complex string hierarchy. The Mozilla Developer Center has a string guide, but not any useful reference documentation.

With a little hand-holding, static analysis tools can produce very useful reference documentation, which other tools simply cannot make. For example, because a static analysis tool knows the accessibility of methods, you can create a reference document that contains only the public API of a class. I spent parts of yesterday and today tweaking a Dehydra script to produce a string reference. I’m working with Eric Shepherd to figure out the best way to automatically upload the data to the Mozilla Developer Center, but I wanted to post a sample for comment. This is the public API of nsACString:

I am trying to keep the format of this document similar to the format we use for interfaces on MDC. It’s a bit challenging, because C++ classes have overloaded method names and frequently have many methods. In the method summary, I have grouped together all the methods with the same name.

Once the output and format are tweaked, I can actually hook the entire generation and upload process to a makefile target, and either run it on my local machine or hook it up to a buildbot. I used E4X to do the actual XML generation. It was a learning experience… I don’t think I’m a fan. I want Genshi for JavaScript. Making conditional constructs in E4X is slightly ugly, and making looping constructs is really painful: my kingdom for an XML generator so that I don’t have to loop and append to an XMLList.

Atom Feed for Comments 4 Responses to “Generating Documentation With Dehydra”

  1. Ted Mielczarek Says:

    Very cool! I wonder if we could use this to feed autocompletion for text editors?

  2. BSBlog » Blog Archive » Generated Documetation, part 2 Says:

    [...] I noted previously, I’ve been using our static analysis tools to generate documentation for the Mozilla string [...]

  3. Bread and Circuits » We could do this Says:

    [...] It got me thinking that a Mozilla version of this would be great as a sidebar extension, which followed me around as I navigated through Mozilla source on the web, found in blogs, pastebin, bugzilla, etc.  I’d love to be able to have the ability to right-click nsIFoo anywhere (not just in MXR) and get all this sort of info  I’d love to be able to do it for Contract IDs too, oh and class members, and static functions, and…We have the power. [...]

  4. visophyte: data made shiny :: dxrpy with references against mailnews, plus bespin wishes Says:

    [...] dxrpy likes to generate documentation using dehydra (bsmedberg’s blog posts on this: 1 2).  I have added support for references/referencedBy extraction and otherwise wailed on it a [...]

Leave a Reply