Documenting dictionaries: revisited

MDN
#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!

Sheppy

1 Like
SubtleCrypto and documenting dictionaries
#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?

#3

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

#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.

Sheppy

#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.

Sheppy

#6

I’ve filed an issue against KumaScript about adding types and dictionaries sections to GroupData.json: https://github.com/mdn/kumascript/issues/584

Sheppy

1 Like
#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?

#8

Do we have a plan to discuss this at any point? Issue 584 has been open for a good long while now (since February 6) and there’s been no debate at all, to my surprise. Given that, I figured I’d go ahead and make an initial suggested syntax.

New members

Add support to each API, at the same level as the existing "interfaces" field, the following optional fields:

  • "dictionaries" – A list of any dictionaries defined by the API. Ideally a complete list but I think that we should retain the option of leaving out dictionaries of limited utility. Syntax is identical to "interfaces".
  • "enums" – A list of any enumerated types defined by the API. See below for specific syntax.
  • "types" – A list of any other types defined by the API. This is just an array of type names. (Or should each entry be a record that indicates the the definition of the type as well as its name?)

Enum entry details

Each "enum" entry should be an object of the following syntax:

"enums":      [ "enumType1",
                "enumType2",
                ...
                "enumTypeN" ]

So, for example, an API that has four enum types used by its methods and structures might have an "enums" section like this (these are largely fake names):

"enums":      [ "AudioChannelOptions",
                "AudioBufferFormat",
                "AudioStreamStatus",
                "AudioStreamReadyState" ]

Any opinions? I’d like to try to see us move forward on this soon.

Sheppy

#9

I guess actually, "types" and "enums" could be a single "types" list.

#10

I wish I had caught this thread earlier. You should have looked at the Payment Request API dictionaries before making a decision about this and regard it as a cautionary example.

The dictionaries of this particular APIs are have a convoluted set of inheritances and nestings. It’s hard to figure out what’s needed for a particular API call. As an API writer, it’s my job to sort this out for developers so that they don’t need to. This policy makes me do the opposite.

#11

I’m not sure I understand what the problem is. I think we can make an intelligent decision about whether to document nested dictionaries as one item or as separate ones.

Frankly, if nested dictionaries are a thing we expect to see more of, we should seriously look at finishing work on macros that can combine them automatically. I’ve been gradually working on a macro that generates much of the content of an API overview page by building the Constructor, Properties, Event handlers, Methods, and a couple of other sections automatically by scanning through GroupData, the page hierarchy, and other sources.

The RTCPeerConnection page actually uses this macro ({{InterfaceOverview}}). RIght now, it just adds at the top of each section a message like “Also inherits properties from: EventTarget, Wonderbar, and SoupKitchen” but could easily be made to instead recurse through the inheritance tree of the interface and combine everything together automatically.

There could even be a tag we could put on pages to say “yeah, don’t include this one when building the inheritance set for another page.”

That would IMHO provide the most generally usable documentation for users.

Sheppy

#12

As I said, it’s hard to figure out what’s needed for a particular call. At one point while documenting payment request I had all the dictionaries printed out, taped together, and with lines drawn to make following the inheritance easier. The problem is that I don’t want web developers burdened with that.

I hope you can solve this problem with a macro. My issue with allowing a mix of both is that someone might assume that dictionaries are required to be documented consistently and ‘correct’ a set of dictionaries that should remain as is.

#13

That’s a good point, and one to try to sort out.

One thing worth considering is documenting them all the same way we do with interfaces, but only include in the sidebars and menus the ones that are more relevant or are used by more than one interface or whatever. That way, macros like {{domxref}} would still have a destination if we use them, but the page wouldn’t get in the way otherwise. We can then use macros like {{page}} (and likely other new ones to simplify the process) to transclude relevant material from those pages into the main body of content on MDN, or to be automatically merged into one long list where inheritance occurs.

Sheppy