-
Notifications
You must be signed in to change notification settings - Fork 22.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
API structure conventions: dictionaries #1948
Comments
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. |
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). |
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. |
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 #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 |
And sometimes other names or actually visible within script or its reference. I don't know how many function have an argument simply named |
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). |
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? |
I propose we move this to the Discussions tracker. |
MDN doesn't consistently document dictionaries.
This came up within the BCD context previously as well in mdn/browser-compat-data#7287
This issue is about making a call on MDN documentation structures.
"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?
The text was updated successfully, but these errors were encountered: