Enum sets

[Eric Shepherd]

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>

[Jean-Yves Perrier]

Hi!

Two advantages to document them in-place.

1. The reader has all the information in the page, without navigating
outside.
2. Enums doesn't exist in JavaScript, they are translated as strings
with a fixed set of values (and a TypeError exception if you try to use
an invalid string). If I'm not mistaken, that means RTCOfferOptions will
never appear as such in the console.

Also quite a few, though not all, webidl enums are used at one single place.

To solve the search problem, we could redirect RTCOfferOptions value to
the createOffer page.

Let's see what others think about it.

--
Jean-Yves

Jean-Yves Perrier
Senior Technical Writer / Mozilla Developer Network

[Sebastian Zartner]

Hi guys,

I'm not having a strong opinion on one or the other, as I don't know how
often we'll have duplicate documentation.
I just want to say that Jean-Yves first point could be handled through a
template. I.e. the 'enums' documentation could be written once on a page
and the macro would take the contents and show them on the API's page.

Sebastian

> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
> MDN contributor guide: http://bit.ly/ContributorGuide
> Doc project Trello board: https://trello.com/b/HAhl54zz/status
>

[Chris Mills]

In my experience so far, enums tend to be specific to an interface*. I’m currently not convinced that it would be worth the extra hassle of documenting them separately, and agree with J-Y’s advantages.

Of course, this might change in the future. Would it be worth talking to the API team about whether they can see any upcoming trend towards reusing enums across interfaces?

Chris

* sometimes for the worse. There is a case in the DataStore API where two different methods (or perhaps properties) are doing the same thing in two slight different contexts, but the enums that provide their options are slightly different, leading to confusion.

[Jeremie Patonnier]

+1 with Jean-Yves and Chris

--
Jeremie
.............................
Web : http://jeremie.patonnier.net
Twitter : @JeremiePat <http://twitter.com/JeremiePat>

[Eric Shepherd]

And I drag this topic back up again… :)

So when we document these in-place, do we list them right with the property they go with or do we have a subsection below where they’re defined?

Personally, I prefer the latter, since it lets the formatting be a little cleaner but mostly because you can then transclude the list of values into other pages if need be. I have run into cases where this is useful, and it reduces clutter in the property list itself as well, making it more readable. It also means that, as Jean-Yves suggested earlier in this thread, we could easily create a page at Web/API/TextTrackKind which redirects to the section “Track kind constants”. That would help with linking and such.

So I’d do something like

Properties

TextTrack.kind
A DOMString which indicates what kind of text track the TextTrack represents. Permitted values are listed under Track kind constants below.

…

Track kind constants
firstkind
Description.

Thoughts?

…

> On Jun 29, 2015, at 4:37 AM, Chris Mills <cmi...@mozilla.com> wrote:
>
> In my experience so far, enums tend to be specific to an interface*. I’m currently not convinced that it would be worth the extra hassle of documenting them separately, and agree with J-Y’s advantages.
>
> Of course, this might change in the future. Would it be worth talking to the API team about whether they can see any upcoming trend towards reusing enums across interfaces?

Eric Shepherd
Senior Technical Writer
Mozilla Developer Network <https://developer.mozilla.org/>
Blog: http://www.bitstampede.com/

<http://www.bitstampede.com/>Twitter: http://twitter.com/sheppy <http://twitter.com/sheppy>

[Sebastian Zartner]

Sounds good to me. One note: I'd make "Track kind constants" and h3 heading
and put it under a "Constants" h2 heading.

Just to be clear, the formatting would be the same as for properties,
right? So, no table layout as I recently used it at
https://developer.mozilla.org/en-US/docs/Web/API/SVGTextContentElement#Constants
?

Sebastian

> Twitter: http://twitter.com/sheppy
>
>