Better formatting for DOM Exceptions

[digitarald]

Questions:

1. How should interface/method names be formatted
2. How should we format/highlight the DOM method part of the error for readability
3. How should we link to the MDN page for the DOM method and the MDN page for the error

Follow up for https://twitter.com/bz_moz/status/1226977763950759938

• Voting where all over the place
• Users would prefer to see document.getElementById referenced in errors, but at runtime we only know the IDL interface name (i.e. Document) (not the path, i.e document)

Another prior discussion is this MDN discussion on how to name methods. @chrisdavidmills summarized it:

Array: from() [STATIC]
Array: isArray() [STATIC]
Array: of() [STATIC]
Array: concat()
Array: copyWithin()

[bzbarsky]

Note that our concept of "MDN page for the error" is somewhat narrow, in the sense that we only have it (for exceptions) for things with an associated JSMSG_*, and not at all for DOMExceptions.

Linking to the DOM method doc in the DOMException case, or even the JS API doc for the JS case, seems more useful than linking to the error if we have to pick one. See also https://twitter.com/bz_moz/status/1228186656236134402.

[digitarald]

@nchevobbe what's possible right now to format/link parts of a log? Does the console grouping template mechanism help?

[nchevobbe]

@nchevobbe what's possible right now to format/link parts of a log? Does the console grouping template mechanism help?

Not sure, we're only replacing URLs with <URL>. I'm not sure why you ask this? Do we want another UI than the [Learn more] link?

[bzbarsky]

We might, yes. We want to conceptually link to at least two places: the description of the method being called and the description of the error that was thrown. See also https://bugzilla.mozilla.org/show_bug.cgi?id=1615518#c2

[nchevobbe]

Okay now I understand. Underlining might not be enough, we could also have the ℹ icon we have in other places to (like in Netmonitor for headers).

Implementation wise, we should probably send additional data from errordocs so we can reference index ranges and matching url in order to not do the work again in the frontend and have everything gathered in one place.

[digitarald]

Reducing the [Learn More] links to (?) icons can also reduce the content/noise ratio in the console a bit.

WDYT, @violasong, is it worth an experiment and is any of the MDN-linking UX exploration for Inspector relevant here?

[violasong]

I've been using (?) in various places, but my initial thought is that the Console can be more obvious about links like this, as the link is more part of the content rather than a side helper-type of UI.

I like the idea of linkifying relevant words if possible. If it's in blue and underlined, that seems prominent enough to me.

[nchevobbe]

Putting the current error message so we can talk about what could be done:

So here we could have Document.getElementById as a link to https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementById , and some other way to link to a page that explain the error.

MDN pages could have a https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementById#Throws page that would explain the error that can be thrown when calling the function. @chrisdavidmills is there already something like this on some pages?

[chrisdavidmills]

@nchevobbe so at the moment we have the error object pages, like

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError

Then we have the JS error pages, for example

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/More_arguments_needed

Then on some WebAPI pages, we have an Exceptions section, for example:

https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Exceptions

This is about the closest we have, and I'm not sure if it is really correct in all situations (some things are actually exceptions, some are errors, etc.) So I'm not sure what the idea section should look like to cover this, but it is probably going to be a lot of work to get all such sections in place.

For the moment, could we just link to the method page without a fragment identifier? That would still be useful, as the user could go straight there to find out what the correct expected syntax is?

Thoughts?

[bzbarsky]

In general, there are a lot of different exceptions that could be thrown by a DOM method. getElementById can only throw for three reasons ("this" is not a document, not enough args, ToString() throwing), but something like https://webaudio.github.io/web-audio-api/#dom-audioworkletglobalscope-registerprocessor can throw for at least 18 reasons not counting various JS-side ones like ToString() throwing @@iterator throwing, etc. Trying to document all the ways things could throw is pretty difficult.

Just linking to the overall method definition would be a great start.

[digitarald]

Just linking to the overall method definition would be a great start.

So in the cases above the [Learn More] link should just link to the method page and we don't even have a second link. Are there cases where we have an error and a method link?

[bzbarsky]

Well, in the "not enough arguments" case in theory we could link to both the method and the MDN description of what the error means. I don't know whether that's actually what we want to do in practice.

[digitarald]

If a DOM method is involved, a simple assumption would be that the method documentation is more helpful than the more generic error docs.