What is the most useful way to present interface lists?

I’ve just rolled out a small update to the interface cross reference, nothing major, just fixing a few bugs and I’ve put up what looks like the final set of interfaces for 1.9.1b2.

I’ve now figured out the best way to gather the interface lists and so the cross reference now includes all interfaces used in all 3 major platforms of Firefox. It is relatively simple for me to add the interfaces for other applications now but this got me thinking about what kind of uses people are making of this and how the multi-OS, multi-app interfaces should be presented. A few ideas came to mind:

  • App developers probably just want to see the interfaces in their app, either only those that appear for all operating systems or those for a specific OS in some cases.
  • Add-on developers probably want to see some kind of shared set of interfaces (what you might call gecko/toolkit) that appear for all apps they are targeting, unfortunately this changes depending on the set of apps. Again they probably want for all OS or for a specific OS.
  • Maybe I shouldn’t even bother doing anything and just include a note in the interface display about where the interface actually exists.

I’m sure other people have other ideas of how it might work, any suggestions?

4 thoughts on “What is the most useful way to present interface lists?”

  1. This is a bit of a pie in the sky idea, but could someone pass an xpi to you to be able to see what interface changes affect their extension?

  2. I’d change the order inside the constants, attributes and methods lists.
    Now you start each element in the list with the description, followed by the term, but it would be much more logical to change it to [[]…], just like html definition lists.

  3. I’d also put this cross reference on MDC. That’s the first place I go looking for documentation anyway, so having the cross reference there makes sense to me.

    Maybe you can add a filtering mechanism to the xref, so that you can collect all info from all applications and platforms and people can filter only the components that are relevant to them.

    And also add a note to each page to show in which applications and on what platforms the interface is defined.

    And a small one line description of each interface on the main overview page might also be very useful.

    Also the top right link to “View IDL” is broken… It appends the encoded URL to the current base href instead of just going there.

    Did I mention that I totally love this overview apart from the few minor remarks above and below? 🙂

  4. Onno, I do hope to get this available in a more useful place, linked from MDC certainly, just waiting on a few bits and pieces first.
    I agree with the idea of filtering the lists, but I’m just not sure what is the best way to present that, short of offering every option under the sun which is going to be very complicated.
    I’ve fixed the broken link.
    I kept the comments before the items because that is how they are presented in IDL. I think it is better to keep it looking pretty much like the source but maybe there is merit in the other approach.

Comments are closed.