With the introduction of enums, something I've been thinking about for a
while has taken on a new level of interest for me.
APIs often have "dictionaries" in their IDL; that is, enums which define
a set of possible values. These can be anything from error codes to
request codes to data type IDs.
For example, consider WebRTC's RTCPeerConnector.createOffer() method
[1]. It accepts as a parameter an RTCOfferOptions value [2].
Currently, we tend to document these in-place, wherever an API
references them. There are problems with this:
1. It can introduce repetition when the same set of values is used in
multiple places.
2. If the dictionary name is used by a user attempting to search MDN,
they find nothing.
I'd like to standardize how we handle cases like this; with enum's
arrival, things like this will become more common, I suspect.
I'm personally leaning toward documenting the dictionary as if it were
an object, style-wise, but with different tagging (that is, tagged
something like "Dictionary" or even "Enums" or "Values" or something.
Each of these would be documented on its own page in the API reference.
Designed properly, they could be embedded in other pages using the
{{page}} macro.
Anyone have feelings to share on this?
[1]
http://bit.ly/1SRgPHL
[2]
http://www.w3.org/TR/webrtc/#idl-def-RTCOfferOptions
--
Eric Shepherd
Senior Technical Writer
Mozilla Developer Network <
https://developer.mozilla.org/>
Blog:
http://www.bitstampede.com/
Twitter: @sheppy <
http://twitter.com/sheppy>