Documenting Error Codes

[Joe Medley]

Gang,

I just saw Florian and Morgan's Mozilla Hacks article on linking to MDN from console error messages. (https://hacks.mozilla.org/2016/06/helping-web-developers-with-javascript-errors). I think this is an excellent move. I have to confess that I haven't paid as much attention to error messages as I should, but I will start doing so in my MDN work.

What concerns me is that there are no standards documented for how to do this, or at least none that I can find.

I can start this discussion with a few observations.

* First, the fact that there were specific pages for error types completely escaped my notice.

* In addition to the error reference link in the article (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors) there are also individual pages for API-specific errors (for example: https://developer.mozilla.org/en-US/docs/Web/API/MediaError).

* I've seen interface member pages that list errors thrown by that member. I couldn't find an example, but it seems they typically reside right after the syntax, whether as a subheading or as the next sibling, I don't remember.

The question is, how exactly should errors be documented on MDN? I'll be happy to help document the answer.

Thanks,
Joe

[Florian Scholz]

Hi Joe!

Am 08.06.2016 um 18:48 schrieb Joe Medley:
> Gang,
>
> I just saw Florian and Morgan's Mozilla Hacks article on linking to MDN from console error messages. (https://hacks.mozilla.org/2016/06/helping-web-developers-with-javascript-errors). I think this is an excellent move. I have to confess that I haven't paid as much attention to error messages as I should, but I will start doing so in my MDN work.

Thanks and great! Happy to get some help with this!

>
> What concerns me is that there are no standards documented for how to do this, or at least none that I can find.
>
> I can start this discussion with a few observations.
>
> * First, the fact that there were specific pages for error types completely escaped my notice.

It is a brand new project that I only started to work on in the last few
weeks on MDN (after finishing the giant WebGL reference btw).

>
> * In addition to the error reference link in the article (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors) there are also individual pages for API-specific errors (for example: https://developer.mozilla.org/en-US/docs/Web/API/MediaError).

The error reference we are talking about in the Hacks article is only
for ECMAScript errors for now. Also it is much more granular than just
"MediaError" or in ECMAScript's case "TypeError", "SyntaxError" etc.

The errors that deserve their own pages are instances of these types of
errors. Here are lists of these for ECMAScript in some engines:
https://dxr.mozilla.org/mozilla-central/source/js/src/js.msg
https://github.com/v8/v8/blob/master/src/messages.h#L75
https://github.com/Microsoft/ChakraCore/blob/master/lib/Parser/rterrors.h

The idea is to create a page for each of those messages, and then link
them from the console. If the engines throw different messages, I am
mentioning both in one article, see e.g.
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Bad_radix

>
> * I've seen interface member pages that list errors thrown by that member. I couldn't find an example, but it seems they typically reside right after the syntax, whether as a subheading or as the next sibling, I don't remember.

In the WebGL reference, for instance.
https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/readPixels#Errors_thrown
Per the style guide we agreed on "Errors thrown" in the syntax section.

>
> The question is, how exactly should errors be documented on MDN? I'll be happy to help document the answer.

I haven't had the time so far, but as I want to grow the amount of error
pages, I will be happily writing a doc on how to get this done!

Florian.

>
> Thanks,
> Joe
> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
> MDN contributor guide: http://bit.ly/ContributorGuide
> Doc project Trello board: https://trello.com/b/HAhl54zz/status

[Eric Shepherd]

Huh. I thought it was "Exceptions". Interesting. I will have to fix a
boatload of pages, both old and new.

Florian Scholz wrote:
> In the WebGL reference, for instance.
> https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/readPixels#Errors_thrown
> Per the style guide we agreed on "Errors thrown" in the syntax section.

--
Eric Shepherd
Senior Technical Writer
Mozilla Developer Network <https://developer.mozilla.org/>
Blog: http://www.bitstampede.com/
Twitter: @sheppy <http://twitter.com/sheppy>

[Chris Mills]

I also thought it was “Exceptions” … ;-|

We should probably have a conversation about this ;-)

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills

[Florian Scholz]

Soooorry :) It is Exceptions! I mixed things up.

Florian Scholz

Technical Writer
Mozilla Developer Network