Documenting dictionaries: revisited

(Eric Shepherd) #1

I’ve brought this up in the past, and the result was kind of a “let’s see how things go” of a thing. I still feel that we should in many if not most cases document dictionaries just like we do interfaces, with an overview page for the dictionary itself and subpages for its properties.

The simple reason is logistics: we have a macro for creating links to API terms (our old friend domxref), which we can’t use to link to dictionary documentation right now. This leaves creating links to information about dictionaries and their members as a weird stand-out – dictionary related reference information is the only thing on all of MDN you can’t get at through macros right now.

While, yes, some dictionaries are very limited in use or are only used as input to a single method, this is more and more often not the case as newer APIs make increasing use of dictionaries (not to mention cases where specifications get updated to change interfaces into dictionaries, as recently happened with some of the RTP interfaces in WebRTC).

Even in cases where the dictionary is used only as input to one parameter (such as when calling a constructor, for example), there are frequently times where you have to refer back to them. For instance, “The behavior of this method varies depending on the value specified as the someDictionaryThing option when setting up your Foo instance.”

I propose that we document all dictionaries exactly as we do interfaces, except for calling them dictionaries (of course), that we add “Dictionary” to our standard set of tags, and that we update the APIRef and any other relevant macros so they find and include dictionaries in lists they generate.

I further propose that we come up with a plan and a solution for embedding inline the information about a dictionary that we currently present when describing parameters that take a dictionary as input, in scenarios where historically we’ve documented the dictionary inline.

The current situation of documenting dictionaries differently in different situations, and the consequent problems with generating links that results from this, is making the documentation more difficult to maintain and to read than necessary. Let’s fix it!


(Chris Mills) #2

Yeah, I think you’re right. Laziness has probably been the only thing stopping me from doing this, perhaps disguised as a belief that it is not worth having separate tree for dictionaries that are only used in one place — a whole tonne of extra work, and all that.

But you are right — they are interfaces, so why treat them any differently?

(Chris Mills) #3

So going forward, write separate trees for all dictionary interfaces?

(Eric Shepherd) #4

Well, they’re not “interfaces,” not really. But they act just about the same for all intents and purposes, and just for the sake of making the documentation consistent I think it makes sense to document them the same way.

The question remains: do we update the sidebars to have a separate section for dictionaries? Or do we update it to still keep them together but to look for both the “Interface” and “Dictionary” tag?

So far, I generally apply both tags to dictionaries when I document them separately, even though that’s not technically correct, just to make sure they show up in the sidebar somewhere. I’d like us to fix that situation though.


(Eric Shepherd) #5

For that matter, I’d like us to add a new section to GroupData called “types” as well, so we can list enumerated types and the like there. These, too, are used more and more often these days, and are not necessarily used in a limited number of places.


(Eric Shepherd) #6

I’ve filed an issue against KumaScript about adding types and dictionaries sections to GroupData.json:


(Chris Mills) #7

@fscholz I’m just flagging this conversation up to you, as we discussed working out a plan for sorting out API docs once and for all. Our conversation focus was mixins, but perhaps this could be a part of it as well?