Sprints: Create new page that shows compares Object methods and their corresponding Reflect namespace methods.

[vaidehijoshi]

Request type

• [x] New documentation

Details

In the process of learning the JavaScript object model and property descriptors, I ran into the MDN docs that describe the Reflect API and the Object constructor API. In the process, I found myself comparing the two APIs.

Currently, the best way to see the differences between both of these APIs seems to be by cross-referencing specific methods and their documentation. For example, if one wanted to see how Reflect.defineProperty differed from Object.defineProperty(), I'd need to go to the specific method's documentation page and look for a note like this:

Unfortunately right now, there is no one place to look for the differences between these two APIs at a glance. I'd like to propose a new page that shows each method in the Object API and its corresponding method in the Reflect namespace.

For example, something like this:

| Method | Object API | Reflect API |
| --- | --- | --- |
| defineProperty() | Returns the object that was passed to the function. Returns a TypeError if the property was not successfully defined on the object.| Returns true if the property was defined on the object and false if it was not. |

I think that this documentation would make is easy for someone to quickly compare and contrast the return value & behavior of each of these APIs without having to dig for each method and then cross-reference it with its equivalent. I'd be happy to add it since I've already started compiling the differences between the two!

[vaidehijoshi]

@chrisdavidmills I have created some documentation for this page, so just let me know when I can go about adding it :)

[chrisdavidmills]

@vaidehijoshi Do you think it would make sense as a subpage underneath https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect?

And what should the title be? "Comparison between Reflect and Object methods" ?

[vaidehijoshi]

@chrisdavidmills I think a subpage would work! Maybe "Comparing Reflect and Object methods"?

[chrisdavidmills]

@vaidehijoshi OK, I've created the page:

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

Feel free to add your content ;-) And don't hesitate to ask if you need any help, want us to review it, etc.

Many thanks.

[vaidehijoshi]

@chrisdavidmills Thanks for creating the page! I have added the content to it :)

I think it would make sense to have it show up on the sidebar of the main Reflect page (maybe underneath the Methods section?). Just thinking that folks would probably be looking for it from that page so it should be easy to find it. Do I need to add that to the Reflect page manually?

I also requested review from a technical standpoint just because I want to be sure that nothing is incorrect in the table!

[chrisdavidmills]

Thank you @vaidehijoshi! I have added a few bits to the document (like the JS Sidebar) and copy edited it.

For other things, I am also alerting @Elchi3 to its existance, so he can think about adding it to sidebars, giving it a tech review, etc.

[Elchi3]

Hey there, thanks for writing this page!

The sidebar is more or less created automatically to reflect (ha!) an object's API. So, you can't easily add links to it. I think we should link it from the main body text, though. (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect#Methods)

The page content generally looks good to me. I think we should have links all over, so you can easily deep dive into all the Object or Reflect methods.

I think the table should focus on the (subtle) differences and not just on what is available on Object vs. on Reflect.
So, e.g. for getOwnPropertyDescriptor you currently have the same description for both, but actually there is a difference as described here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/getOwnPropertyDescriptor#Difference_to_Object.getOwnPropertyDescriptor()

[vaidehijoshi]

@Elchi3 Thanks for the review! I'll do another pass through for all the subtleties (I _thought_ I caught all of them, like getPrototypeOf and isExtensible, which definitely have subtle differences between them). I'll also go through add links to the appropriate methods and add it to the Reflect main body text, as you suggested.

Will ping you here once it's updated so you can take a look at it :)

[vaidehijoshi]

@Elchi3 + @chrisdavidmills I've gone ahead and done another pass through this page:

• [x] Added a link to the page from the main body text of Reflect.
• [x] Added links back to each API method throughout the table to help folks find the appropriate method.
• [x] Also did another pass through all of the methods to include subtle differences between each.

Let me know if you think that there is anything else to be done here 🙂

[Elchi3]

Thanks for doing this, I think we can call this done now. Really great work! :+1: Cheers!

[vaidehijoshi]

Thanks for all your help and review! 😸