Improving the API references

I forgot to add to my last post some information about what I currently had in mind to improve about the API reference I’ve been working on. Any further suggestions people have are very welcome, but here is the current few ideas I have.

Currently it only indexes Firefox and Gecko interfaces, in fact it only indexes those used by an OSX build of Firefox. It would be nice to be able to index interfaces for all the main applications and for all the platforms. There are a couple of issues with this. Firstly I’d want the UI to work so people viewing it could select what set of interfaces they wanted to see. Secondly actually building the lists of interfaces for each application and OS is going to be pretty tricky I think. So far I’ve resorted to building Firefox then looking in dist/idl. This works but it is time consuming. Possibly I might be able to come up with some clever nonsense to make the build system only compile idls but we’ll see.

It would be nice to be able to include a list of the component contract ids available in the platform and what interfaces they implement. This is I think pretty difficult to do just by parsing the source files. Potentially a little extension could run in the app and do some looking through Components.classes to find this out. One issue here though is there is no way to tell whether components are services or not so instantiating them is potentially problematic. This is a problem that could be solved by brute force, or maybe doing a special instrumented build.

So those are my main two ideas, if anyone has any suggestions on how to make those tasks easier or for other things that should be there then shout them out.

4 thoughts on “Improving the API references”

  1. We could make nightly or even hourly builds hand a copy/package of dist/idl out to some publicly available places, if that helps. This should take a lot of time for the boxes to do, but could easily provide a copy for all platforms. Would that help? I could look myself into doing that for SeaMonkey, if wanted.
    Else, only doing “make export” across the tree might actually work to give you the IDLs in that dir but I’m not sure if it works flawlessly do do only that step.

    For the contract IDs, I guess with an external tool, you’d need to go decode all .xpt files. An extension should be possible, and again I could imagine hooking into a box, possibly running that extension like we do run tests, possibly by calling a -chrome parameter with a file of the extension and that would loop through the classes and hand you the result in some way, perhaps even through a HTTP connection or such.

  2. I’m doing something similar to export bindings from IDL to GWT-compatible Java (different enough than the Java bindings to be problematic with the xpidl compiler). I’m running into some of the same issues that you are.

    Having the pre-packaged IDL available for all the products would make life way easier. Adding a pre-computed list of contract ID to interface mappings would be gravy. 🙂

  3. Robert: The xpt files hold the interface definitions, not the components that implement them. For that you pretty much have to run the build then look in compreg.dat, but even then that just gives you the names.
    The idea about uploading something after builds is an interesting one, however mentioning xpts has made me have another idea. As it is I parse the idls to get the interface definitions. Parsing the compiled xpts themselves is an alternate way, except I believe you lose bits like comments etc. However I could use the xpt from a build to say what interfaces are present and then just parse those from the source. That means all I have to do is pull the nightly archives and extract the xpt files to get all the information I need I think. That could be worth a try.

  4. My knowledge about Mozilla’s build system is limited, so forgive me if this seems ridiculous, but I guess you can somehow override the XPIDL_COMPILE variable in config/ (and possibly nuke XPIDL_LINK) with the tool you’re using for parsing the IDLs, and then run make export at the top level. This should catch all IDL files and pass them to your own parser program instead of the XPIDL compiler.

    I suspect that this should catch all of the IDL files in the tree, but it would be simple to test. Just run the suite once with this method and once with the old method you’ve been using, and then compare the results using a simple query.

    Hope this helps!

Comments are closed.