LibJS: Add ECMA-262 section/title/URL comments almost everywhere

As mentioned on Discord earlier, we'll add these to all new functions
going forward - this is the backfill. Reasons:

- It makes you look at the spec, implementing based on MDN or V8
  behavior is a no-go
- It makes finding the various functions that are non-compliant easier,
  in the future everything should either have such a comment or, if it's
  not from the spec at all, a comment explaining why that is the case
- It makes it easier to check whether a certain abstract operation is
  implemented in LibJS, not all of them use the same name as the spec.
  E.g. RejectPromise() is Promise::reject()
- It makes it easier to reason about vm.arguments(), e.g. when the
  function has a rest parameter
- It makes it easier to see whether a certain function is from a
  proposal or Annex B

Also:

- Add arguments to all functions and abstract operations that already
  had a comment
- Fix some outdated section numbers
- Replace some ecma-international.org URLs with tc39.es

1 files changed, 25 insertions, 7 deletions

diff --git a/Userland/Libraries/LibJS/Runtime/ObjectConstructor.cpp b/Userland/Libraries/LibJS/Runtime/ObjectConstructor.cpp
index 489335fa28..54982e4bd7 100644
--- a/Userland/Libraries/LibJS/Runtime/ObjectConstructor.cpp
+++ b/Userland/Libraries/LibJS/Runtime/ObjectConstructor.cpp
@@ -24,7 +24,10 @@ void ObjectConstructor::initialize(GlobalObject& global_object)
 {
     auto& vm = this->vm();
     NativeFunction::initialize(global_object);
+
+    // 20.1.2.19 Object.prototype, https://tc39.es/ecma262/#sec-object.prototype
     define_property(vm.names.prototype, global_object.object_prototype(), 0);
+
     define_property(vm.names.length, Value(1), Attribute::Configurable);
 
     u8 attr = Attribute::Writable | Attribute::Configurable;
@@ -54,6 +57,7 @@ ObjectConstructor::~ObjectConstructor()
 {
 }
 
+// 20.1.1.1 Object ( [ value ] ), https://tc39.es/ecma262/#sec-object-value
 Value ObjectConstructor::call()
 {
     auto value = vm().argument(0);
@@ -62,11 +66,13 @@ Value ObjectConstructor::call()
     return value.to_object(global_object());
 }
 
+// 20.1.1.1 Object ( [ value ] ), https://tc39.es/ecma262/#sec-object-value
 Value ObjectConstructor::construct(Function&)
 {
     return call();
 }
 
+// 20.1.2.10 Object.getOwnPropertyNames ( O ), https://tc39.es/ecma262/#sec-object.getownpropertynames
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::get_own_property_names)
 {
     auto* object = vm.argument(0).to_object(global_object);
@@ -75,6 +81,7 @@ JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::get_own_property_names)
     return Array::create_from(global_object, object->get_own_properties(PropertyKind::Key, false, GetOwnPropertyReturnType::StringOnly));
 }
 
+// 20.1.2.11 Object.getOwnPropertySymbols ( O ), https://tc39.es/ecma262/#sec-object.getownpropertysymbols
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::get_own_property_symbols)
 {
     auto* object = vm.argument(0).to_object(global_object);
@@ -83,6 +90,7 @@ JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::get_own_property_symbols)
     return Array::create_from(global_object, object->get_own_properties(PropertyKind::Key, false, GetOwnPropertyReturnType::SymbolOnly));
 }
 
+// 20.1.2.12 Object.getPrototypeOf ( O ), https://tc39.es/ecma262/#sec-object.getprototypeof
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::get_prototype_of)
 {
     auto* object = vm.argument(0).to_object(global_object);
@@ -91,6 +99,7 @@ JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::get_prototype_of)
     return object->prototype();
 }
 
+// 20.1.2.21 Object.setPrototypeOf ( O, proto ), https://tc39.es/ecma262/#sec-object.setprototypeof
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::set_prototype_of)
 {
     auto* object = vm.argument(0).to_object(global_object);
@@ -114,6 +123,7 @@ JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::set_prototype_of)
     return object;
 }
 
+// 20.1.2.14 Object.isExtensible ( O ), https://tc39.es/ecma262/#sec-object.isextensible
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::is_extensible)
 {
     auto argument = vm.argument(0);
@@ -122,7 +132,7 @@ JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::is_extensible)
     return Value(argument.as_object().is_extensible());
 }
 
-// 20.1.2.15 Object.isFrozen, https://tc39.es/ecma262/#sec-object.isfrozen
+// 20.1.2.15 Object.isFrozen ( O ), https://tc39.es/ecma262/#sec-object.isfrozen
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::is_frozen)
 {
     auto argument = vm.argument(0);
@@ -131,7 +141,7 @@ JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::is_frozen)
     return Value(argument.as_object().test_integrity_level(Object::IntegrityLevel::Frozen));
 }
 
-// 20.1.2.16 Object.isSealed, https://tc39.es/ecma262/#sec-object.issealed
+// 20.1.2.16 Object.isSealed ( O ), https://tc39.es/ecma262/#sec-object.issealed
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::is_sealed)
 {
     auto argument = vm.argument(0);
@@ -140,6 +150,7 @@ JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::is_sealed)
     return Value(argument.as_object().test_integrity_level(Object::IntegrityLevel::Sealed));
 }
 
+// 20.1.2.18 Object.preventExtensions ( O ), https://tc39.es/ecma262/#sec-object.preventextensions
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::prevent_extensions)
 {
     auto argument = vm.argument(0);
@@ -155,7 +166,7 @@ JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::prevent_extensions)
     return argument;
 }
 
-// 20.1.2.6 Object.freeze, https://tc39.es/ecma262/#sec-object.freeze
+// 20.1.2.6 Object.freeze ( O ), https://tc39.es/ecma262/#sec-object.freeze
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::freeze)
 {
     auto argument = vm.argument(0);
@@ -171,7 +182,7 @@ JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::freeze)
     return argument;
 }
 
-// 20.1.2.20 Object.seal, https://tc39.es/ecma262/#sec-object.seal
+// 20.1.2.20 Object.seal ( O ), https://tc39.es/ecma262/#sec-object.seal
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::seal)
 {
     auto argument = vm.argument(0);
@@ -187,6 +198,7 @@ JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::seal)
     return argument;
 }
 
+// 20.1.2.8 Object.getOwnPropertyDescriptor ( O, P ), https://tc39.es/ecma262/#sec-object.getownpropertydescriptor
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::get_own_property_descriptor)
 {
     auto* object = vm.argument(0).to_object(global_object);
@@ -198,6 +210,7 @@ JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::get_own_property_descriptor)
     return object->get_own_property_descriptor_object(property_key);
 }
 
+// 20.1.2.4 Object.defineProperty ( O, P, Attributes ), https://tc39.es/ecma262/#sec-object.defineproperty
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::define_property_)
 {
     if (!vm.argument(0).is_object()) {
@@ -226,7 +239,7 @@ JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::define_property_)
     return &object;
 }
 
-// 20.1.2.3 Object.defineProperties, https://tc39.es/ecma262/#sec-object.defineproperties
+// 20.1.2.3 Object.defineProperties ( O, Properties ), https://tc39.es/ecma262/#sec-object.defineproperties
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::define_properties)
 {
     if (!vm.argument(0).is_object()) {
@@ -241,11 +254,13 @@ JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::define_properties)
     return &object;
 }
 
+// 20.1.2.13 Object.is ( value1, value2 ), https://tc39.es/ecma262/#sec-object.is
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::is)
 {
     return Value(same_value(vm.argument(0), vm.argument(1)));
 }
 
+// 20.1.2.17 Object.keys ( O ), https://tc39.es/ecma262/#sec-object.keys
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::keys)
 {
     auto* obj_arg = vm.argument(0).to_object(global_object);
@@ -255,6 +270,7 @@ JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::keys)
     return Array::create_from(global_object, obj_arg->get_enumerable_own_property_names(PropertyKind::Key));
 }
 
+// 20.1.2.22 Object.values ( O ), https://tc39.es/ecma262/#sec-object.values
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::values)
 {
     auto* obj_arg = vm.argument(0).to_object(global_object);
@@ -264,6 +280,7 @@ JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::values)
     return Array::create_from(global_object, obj_arg->get_enumerable_own_property_names(PropertyKind::Value));
 }
 
+// 20.1.2.5 Object.entries ( O ), https://tc39.es/ecma262/#sec-object.entries
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::entries)
 {
     auto* obj_arg = vm.argument(0).to_object(global_object);
@@ -273,7 +290,7 @@ JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::entries)
     return Array::create_from(global_object, obj_arg->get_enumerable_own_property_names(PropertyKind::KeyAndValue));
 }
 
-// 20.1.2.2 Object.create, https://tc39.es/ecma262/#sec-object.create
+// 20.1.2.2 Object.create ( O, Properties ), https://tc39.es/ecma262/#sec-object.create
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::create)
 {
     auto prototype_value = vm.argument(0);
@@ -300,6 +317,7 @@ JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::create)
     return object;
 }
 
+// 1 Object.hasOwn ( O, P ), https://tc39.es/proposal-accessible-object-hasownproperty/#sec-object.hasown
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::has_own)
 {
     auto* object = vm.argument(0).to_object(global_object);
@@ -311,7 +329,7 @@ JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::has_own)
     return Value(object->has_own_property(property_key));
 }
 
-// 20.1.2.1 Object.assign, https://tc39.es/ecma262/#sec-object.assign
+// 20.1.2.1 Object.assign ( target, ...sources ), https://tc39.es/ecma262/#sec-object.assign
 JS_DEFINE_NATIVE_FUNCTION(ObjectConstructor::assign)
 {
     auto* to = vm.argument(0).to_object(global_object);