I took a break the last couple of days from writing Firefox 4 documentation to put together some new templates to help improve the look and feel of our Interface Reference documentation. The one that’s exposed directly to you is the new
IFSummary template, which replaces the old
InterfaceStatus template that we used to use at the top of articles. The
InterfaceStatus template now actually calls through to
IFSummary, although it doesn’t take as many parameters so the results are suboptimal.
This creates a much better box at the top of the page presenting in a consistent format key information about the interface. For example:
There are tooltips displayed as you mouse over the version timeline indicating details; for example, the yellow dot (which is round in browsers supporting
border-radius) indicates the version in which the interface last changed; mousing over the dot gives a tooltip with the exact version number.
Here’s a list of all the parameters the template accepts:
- Path of the IDL file defining the interface
- This is used to create a link to the interface’s IDL on MXR so the reader can refer to it if they wish.
- Parent interface
- This is the name of the interface upon which the interface being document is based. This will be turned into a link to that interface in the interface reference and displayed.
- scriptable/not scriptable
- A string indicating whether the interface is scriptable or not. You must use either “scriptable” or “not scriptable” (these are, however, case insensitive). This will be turned into an appropriate indicator in the box, colored green for scriptable interfaces or red for non-scriptable ones. The indicator will also include a link to an article explaining what this means.
- Last changed in what Gecko version
- This is a string indicating the version of Gecko in which the interface was last changed. Should be a string in standard Gecko version format, such as “1.9” or “1.9.2” or even “188.8.131.52”.
- Summary (optional)
- A brief textual summary of what the interface does. Should be just a sentence or two. This is only optional for backward compatibility with old interface documents using the now deprecated InterfaceStatus template (which now calls through to this one). You should always provide this.
- Version introduced (optional)
- If you know the version of Gecko in which the interface was introduced, include that here. This will trigger the inclusion of a version timeline showing the availability of the interface in contrast to the history of Gecko, in graphical format.
- Version deprecated (optional)
- If the interface is deprecated, include that here. This will be used when drawing the version timeline diagram.
- Version obsoleted (optional)
- Similarly, if the interface is obsolete and no longer available at all, include the Gecko version in which that took effect.
Under the hood, the VersionTimeline template generates the actual version timeline chart, and even further under the hood is the xverblob template, which takes a version number in the format w[.x[.y[.z]]] and constructs an integer value that can be used to compare two versions or do other math (such as taking a version, comparing to another version, and generating a percentage of one as compared to the other). This might be useful in other templates in the future.
Although I’m sure there will be changes to these templates over time, I’ve updated the custom templates documentation with this information as well as several examples, and the sample interface reference article page has likewise been updated. You should take a look!