MDN Web Docs
API structure conventions: dictionaries #581
-
|
MDN doesn't consistently document dictionaries. "Web IDL dictionaries are a spec author convenience for describing plain JavaScript objects. Dictionaries are typically used as arguments, often for init dictionaries for constructors, and sometimes as the return types for methods." says @foolip. On MDN you can find dictionaries documented in at least three forms:
What is best? I've been documenting things inline (like in the canvas case), so I'm a fan of option 3. @sideshowbarker summarizes well what I'm thinking, too (mdn/browser-compat-data#7287 (comment))
Thoughts? |
Beta Was this translation helpful? Give feedback.
Replies: 0 comments 13 replies
-
|
I prefer (3) although I suspect there are cases where (2) is more appropriate, e.g.:
In other words, I think (3) makes the best default approach, but we should probably leave room for (2) when warranted; I think (1) is an overkill in general. Another thought: I don't think it's useful for MDN to be talking about "dictionaries" and/or to name them, as in:
From a JS developer perspective, dictionaries aren't a thing; and the name given to a dictionary is not something they don't particularly need to be aware of. I don't know if this is a consideration for this issue, or one that ought to be discussed separately. |
Beta Was this translation helpful? Give feedback.
-
Unless they have former Python knowledge, where a I have no strong feelings about either option (since I haven't get my hands dirty with making changes on MDN yet). |
Beta Was this translation helpful? Give feedback.
-
|
I also prefer 3, granting that it, like #1940 also argues for a reuse or inclusion mechanism. The poster child for this is the Payment APIs. The data used in a transaction has similar structures in different places. To even get a handle on this when documenting it, I printed all the structures, taped them into one sheet of paper, and drew lines to indicate, which properties pointed to which child structures. This is an extreme example, but it illustrates a principle that I've always believed about technical writing; my job is to resolve confusion so that developers don't need to. |
Beta Was this translation helpful? Give feedback.
-
|
I don't think my opinion should count for much when it comes to what's best for web developer documentation, but @dontcallmedom's comments in mdn/content#1948 (comment) match my own views. Because dictionaries are just plain objects in JS their names are invisible, but I'm not sure how to describe common shapes of objects with giving them a name. I would also say that the fact that Web IDL dictionaries are just JS objects doesn't necessarily mean the terminology should be avoided on MDN. Compare it to Web IDL interfaces are function objects in JS and could be described as objects (like |
Beta Was this translation helpful? Give feedback.
-
And sometimes other names or actually visible within script or its reference. I don't know how many function have an argument simply named |
Beta Was this translation helpful? Give feedback.
-
In ye olden days, this was called the „Configuration Object Pattern” and used to „trim down” the number of arguments (and define sane defaults etc). |
Beta Was this translation helpful? Give feedback.
-
|
I would also prefer 3, with an option for 2 if the dictionary definition gets particularly long and troublesome. In fact, a useful half-way-house approach might be to provide a really quick description of each property inside the object, and then point to a separate page for the full information if you need it, e.g. Parametersoptions A dictionary object containing the following properties:
If you need more detailed information about these properties, see the BlahDictionaryObject page. The above approach is basically what I've always told MDN contributors to do anyway. Always having a separate page for every dictionary is just overkill. In terms of naming dictionaries, I agree with @dontcallmedom ; we should avoid it as much as much as possible. The only places we should mention an actual dictionary name are in the link to the separate object page, if there is one. In terms of what to generically refer to the dictionary object as, I've used "dictionary object" above, but we can probably even just say "object". Do we even need to mention the word "dictionary" at all? |
Beta Was this translation helpful? Give feedback.
-
|
This has come up again in mdn/content#5975 (comment) where there is going to be a removal of 4 dictionaries from BCD. I have back linked to here, but we might want to have a summary somewhere of the result of this discussion. My understanding of the above is that we're using dictionaries for the same reason spec authors do - to avoid having to duplicate common ideas lots of times. The consensus seems to be that if the dictionary can reasonably be included inline then it should be - we are happy to live with a certain amount of duplication and reuse to simplify things for developers (not introduce names for things that have no relevance to API users). We're a bit stalled on what to do when a dictionary object is reused a lot of times, but since we're not running a project to "fix" this right now, that hasn't caused a problem. Is that about right? My only thought on top of this is that the name of a dictionary isn't relevant to end users until it is - when they end up in the spec. So I don't think I have a problem having text like "this object is referred to as XXX in the spec". |
Beta Was this translation helpful? Give feedback.
-
|
It sounds right to me. |
Beta Was this translation helpful? Give feedback.
-
|
I think this is answered: Option 3, unless there is a case for a separate page as per the above comments 👍 I do have one query - how do we know if a dictionary is reused elsewhere? I'm hoping it's in IDL but I'm not sure I've come across a case yet. I've added a personal todo to include this when I go through contributor docs. |
Beta Was this translation helpful? Give feedback.
-
What do you mean? In the MDN docs before cleanup it is obvious from the fact that the dictionary is documented separately. After cleaning up the docs though you don't know there was ever a reused dictionary (and the point then is it does not matter, because the dictionary was only ever used as a convenience for docs and spec authors). |
Beta Was this translation helpful? Give feedback.
-
|
@Rumyra one can figure this out with a checkout of https://github.com/w3c/webref/tree/master/ed/idl, searching that repo/directory for the dictionary name. |
Beta Was this translation helpful? Give feedback.
-
|
Yes this is irrelevant to authors @hamishwillee it was merely something I was thinking about :) Thanks @foolip that's a great tip 👍 |
Beta Was this translation helpful? Give feedback.
I prefer (3) although I suspect there are cases where (2) is more appropriate, e.g.:
In other words, I think (3) makes the best default approach, but we should probably leave room for (2) when warranted; I think (1) is an overkill in general.
Another thought: I don't think it's useful for MDN to be talking about "dictionaries" and/or to name them, as in:
From a JS developer perspective, dictionaries aren't a thing; an…