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.

API reference updates

Since my first announcement about my little api reference tool I’ve slowly been working on updates to make it more useful and easier to navigate around. I’ve now gone and pushed the latest version live. A few of the new features:

  • The main and platform lists of interfaces are split by the module where the interface lives.
  • Interface lists have a quick filter box, type in it to filter the list quickly.
  • Any interfaces used as return types or parameters are now links to get you straight to the information about them.
  • Full IDL support so it now lists all the special attributes and for the uninitiated they have tooltips that explain what they mean.
  • You can now list all usage of an interface by other interfaces.
  • Constants are ordered the same as in the source IDL since they tend to make more sense that way.
  • Includes direct links to the source IDL file.

I’ve also updated the database with the latest APIs in 1.9.1b2pre and as soon as 1.9.1b2 is frozen I’ll update it again just to be sure it has the latest versions.

You can also search the API for interfaces. There isn’t any UI for this right now but it is perfectly set up for a smart bookmark. Just use http://www.oxymoronical.com/experiments/apidocs/search/interface/%s for the url and an appropriate keyword and you can do quick searches for substrings of the interface name.