Improve Proxy documentation

[wbamberg]

This came up in mdn/stumptown-content#447.

Our documentation for the JavaScript Proxy object is confusing and badly organized.

The main page: Proxy describes the Proxy class, so it should have a "Constructor" section linking to a separate page describing its constructor.

Instead it has "Syntax" that describes the constructor call. This is a pattern we've been removing the other JS docs.

But it also has "Instance methods" listing things like handler.getPrototypeOf(). These are not instance methods of Proxy. They are functions you can define on the handler argument to the Proxy constructor. It is very confusing to organize them like this.

I think we should have a new Proxy() constructor page, with a big section called "Handler methods", that describes all the handler methods, using content from the subpages of handler. Correspondingly we should remove handler and all the pages underneath it, and make them redirect to the Proxy() constructor page.

This does mean that we will have a quite huge Proxy() constructor page, but at least its organization will make sense.

We should also make sure the main Proxy page has a good description of how to use this and why you might want to. https://hacks.mozilla.org/2015/07/es6-in-depth-proxies-and-reflect/ is good source material here.

[wbamberg]

I've written a basic Proxy() constructor page.

I think the main question is what to do about all the handler pages.

The story with the handler object is I think: you construct a Proxy with 2 arguments, target (the object you are proxying) and handler. The handler argument is an object, and you define on it any operations that you want to intercept (like get, defineProperty etc).

At the moment we document this with a hierarchy of pages like:

• Proxy: the page for the Proxy class, which lists handler methods under "Instance methods".
  • handler: a catalogue of the methods you can define on handler
    • handler.get: a subpage for each of the methods you can define on handler
    • etc

There are semantic problems with this that I think have a real effect on the usability of this documentation:

1. Proxy: lists handler methods under "Instance methods". This implies that when I create a Proxy I can call things like myProxy.defineProperty(), which I can't of course.

2. handler: is tagged as a namespace, which it isn't.

3. The methods of handler are presented as normal JS methods, but they're not. In the JS documentation I expect methods to be things I can call: but these methods are things I define that are called by the Proxy mechanism.

From a purist point of view, what I am tempted to do is:

• make the handler page and its subpages redirect to the Proxy() constructor page.
• add a new section in the Proxy() constructor page that describes all the handler methods as methods you can define on the handler argument.

But this will make the constructor page very long, and means we'll have to change the way handler methods are described (because the heading hierarchy won't work when the documentation for a handler is under an H2 rather than in a standalone page).

So I think I'd like to:

• keep the separate handler pages, but just indicate that they don't describe "normal" JS methods, but instead methods you can define on the handler argument
• move the handler pages under the Proxy() constructor page
• make the handler page redirect to the Proxy() constructor page
• add a section to the Proxy() constructor page that lists and links to the handler method pages.
• delete the "Instance methods" section from the main Proxy page.

@Elchi3 , what do you think?

[wbamberg]

A close analogy to this seems to be the Promise() documentation, where the constructor takes an executor function with a particular signature and expected behavior. We don't have a separate "javascript-method" page at Promise/executor for this: we document it in the Promise() constructor page as an argument.

[Elchi3]

Thanks for this detailed research, Will!

I think this problem reminds me of another debate in API docs, that I'd call "The Great Dictionary Debate": Should dictionaries, or generally, complex constructor parameters be split out into sub pages (or even pages in the main API namespace), or should they be presented inline?

We haven't agreed on structures for this and so, yes, as you say, oftentimes our current structures make no sense semantically.

That said, I like the plan you've proposed for Proxy handlers and I think this topic will come back once we talk about structuring API docs. For now, I'd say we can go ahead with restructuring like you've proposed and see how it feels.

[wbamberg]

I've made all the changes proposed in #3268 (comment) and added BCD for the Proxy() constructor.