js API documentation (#7568)

- Mostly everything is from the great docs of MDN. Appropriate credit given.

std/js/JsIterator.hx

@@ -1,11 +1,16 @@
 package js;
 
-// prefixed with Js to avoid name clashes with standard Iterator structure
-
+/**
+	JsIterator is prefixed with Js to avoid name clashes with standard 
+	Iterator structure.
+**/
 typedef JsIterator<T> = {
 	function next():JsIteratorStep<T>;
 }
 
+/**
+	Object returned by `JsIterator.next`.
+**/
 typedef JsIteratorStep<T> = {
 	done:Bool,
 	?value:T

std/js/Map.hx

@@ -21,21 +21,88 @@
  */
 package js;
 
+/**
+	The (native) JavaScript Map object holds key-value pairs. 
+	Any value (both objects and primitive values) may be used as either a key
+	or a value.
+	
+	Documentation [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) by [Mozilla Contributors](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map$history), licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/).
+**/
 @:native("Map")
 extern class Map<K,V> {
+	/** 
+		The number of key/value pairs in the `js.Map` object. 
+	**/
 	var size(default,null):Int;
+
+	/**
+		An Array or other iterable object whose elements are key-value pairs 
+		(arrays with two elements, e.g. `[[ 1, 'one' ],[ 2, 'two' ]]`).
+		Each key-value pair is added to the new `js.Map`; 
+		null values are treated as undefined.
+	**/
 	@:pure function new(?iterable:Any);
+
+	/** 
+		A boolean asserting whether a value has been associated to the key in 
+		the `js.Map` object or not.
+	**/
 	@:pure function has(key:K):Bool;
+
+	/**
+		The value associated to the key, or `null` if there is none.
+	**/
 	@:pure function get(key:K):Null<V>;
+
+	/**
+		Sets the value for the key in the Map object. 
+		Returns the `js.Map` object.
+	**/
 	function set(key:K, value:V):Map<K,V>;
+
+	/**
+		Returns `true` if an element in the `js.Map` object existed and has been
+		removed, or `false` if the element does not exist. 
+		`has(key)` will return `false` afterwards.
+	**/
 	function delete(key:K):Bool;
+
+	/**
+		Removes all key/value pairs from the Map object.
+	**/
 	function clear():Void;
+
+	/**
+		Calls `callback` once for each key-value pair present in the `js.Map` 
+		object, in insertion order. 
+		
+		If a `thisArg` parameter is provided to forEach, it will be used as the
+		`this` value for each callback.
+	**/
 	function forEach(callback:(value:V, key:K, map:Map<K,V>)->Void, ?thisArg:Any):Void;
+
+	/**
+		Returns a new `JsIterator` object that contains the keys for each element 
+		in the `js.Map` object in insertion order.
+	**/
 	function keys():JsIterator<K>;
+
+	/**
+		Returns a new `JsIterator` object that contains the values for each 
+		element in the `js.Map` object in insertion order.
+	**/
 	function values():JsIterator<V>;
+
+	/**
+		Returns a new `JsIterator` object that contains an array of `MapEntry`
+		for each element in the `js.Map` object in insertion order.
+	**/
 	function entries():JsIterator<MapEntry<K,V>>;
 }
 
+/**
+	Key/value access helper for `js.Map.entries()` and `js.Set.entries()`.
+**/
 abstract MapEntry<K,V>(Array<Any>) {
 	public var key(get,never):K;
 	public var value(get,never):V;

std/js/Object.hx

@@ -24,43 +24,202 @@ package js;
 import haxe.extern.Rest;
 import haxe.DynamicAccess;
 
+/**
+	The `js.Object` constructor creates an object wrapper.
+	
+	Documentation [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) by [Mozilla Contributors](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object$history), licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/).
+**/
 @:native("Object")
 extern class Object {
+	/**
+		Copies the values of all enumerable own properties from one or more 
+		source objects to a target object.
+	**/
 	static function assign<T:{}>(target:T, sources:Rest<{}>):T;
+
+	/**
+		Creates a new object with the specified prototype object and properties.
+	**/
 	@:pure static function create<T>(proto:{}, ?propertiesObject:DynamicAccess<ObjectPropertyDescriptor>):T;
+
+	/**
+		Adds the named properties described by the given descriptors to an object.
+	**/
 	static function defineProperties<T:{}>(obj:T, props:DynamicAccess<ObjectPropertyDescriptor>):T;
+
+	/**
+		Adds the named property described by a given descriptor to an object.
+	**/
 	static function defineProperty<T:{}>(obj:T, prop:String, descriptor:ObjectPropertyDescriptor):T;
+
+	/**
+		Freezes an object: other code can't delete or change any properties.
+	**/
 	static function freeze<T:{}>(obj:T):T;
+
+	/**
+		Returns a property descriptor for a named property on an object.
+	**/
 	@:pure static function getOwnPropertyDescriptor(obj:{}, prop:String):Null<ObjectPropertyDescriptor>;
+
+	/**
+		Returns an array containing the names of all of the given object's own 
+		enumerable and non-enumerable properties.
+	**/
 	@:pure static function getOwnPropertyNames(obj:{}):Array<String>;
+
+	/**
+		Returns an array of all symbol properties found directly upon a given object.
+	**/
 	@:pure static function getOwnPropertySymbols(obj:{}):Array<Symbol>;
+
+	/**
+		Returns the prototype of the specified object.
+	**/
 	@:pure static function getPrototypeOf<TProto:{}>(obj:{}):Null<TProto>;
+
+	/**
+		Compares if two values are the same value. Equates all NaN values 
+		(which differs from both Abstract Equality Comparison and 
+		Strict Equality Comparison).
+	**/
 	@:pure static function is<T>(value1:T, value2:T):Bool;
+
+	/**
+		Determines if extending of an object is allowed.
+	**/
 	@:pure static function isExtensible(obj:{}):Bool;
+
+	/**
+		Determines if an object was frozen.
+	**/
 	@:pure static function isFrozen(obj:{}):Bool;
+
+	/**
+		Determines if an object is sealed.
+	**/
 	@:pure static function isSealed(obj:{}):Bool;
+
+	/**
+		Returns an array containing the names of all of the given object's own 
+		enumerable string properties.
+	**/
 	@:pure static function keys(obj:{}):Array<String>;
+
+	/**
+		Prevents any extensions of an object.
+	**/
 	static function preventExtensions<T:{}>(obj:T):T;
+
+	/**
+		Prevents other code from deleting properties of an object.
+	**/
 	static function seal<T:{}>(obj:T):T;
+
+	/**
+		Sets the prototype (i.e., the internal Prototype property).
+	**/
 	static function setPrototypeOf<T:{}>(obj:T, prototype:Null<{}>):T;
+
+	/**
+		Allows the addition of properties to all objects of type Object.
+	**/
 	static var prototype(default,never):ObjectPrototype;
+
+	/**
+		The Object constructor creates an object wrapper.
+	**/
 	@:pure function new(?value:Any);
 }
 
+/**
+	Type for 
+	@see <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object>
+**/
 typedef ObjectPrototype = {
+	/**
+		Returns a boolean indicating whether an object contains the specified 
+		property as a direct property of that object and not inherited through 
+		the prototype chain.
+	**/
 	var hasOwnProperty(default,never):Function;
+
+	/**
+		Returns a boolean indicating whether the object this method is called 
+		upon is in the prototype chain of the specified object.
+	**/
 	var isPrototypeOf(default,never):Function;
+
+	/**
+		Returns a boolean indicating if the internal enumerable attribute is set.
+	**/
 	var propertyIsEnumerable(default,never):Function;
+
+	/**
+		Calls `toString()`.
+	**/
 	var toLocaleString(default,never):Function;
+
+	/**
+		Returns a string representation of the object.
+	**/
 	var toString(default,never):Function;
+
+	/**
+		Returns the primitive value of the specified object.
+	**/
 	var valueOf(default,never):Function;
 }
 
+/**
+	@see <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty>
+**/
 typedef ObjectPropertyDescriptor = {
+	/**
+		`true` if and only if the type of this property descriptor may be 
+		changed and if the property may be deleted from the corresponding object.
+		
+		Defaults to `false`.
+	**/
 	@:optional var configurable:Bool;
+
+	/**
+		`true` if and only if this property shows up during enumeration of the
+		properties on the corresponding object.
+		
+		Defaults to `false`.
+	**/
 	@:optional var enumerable:Bool;
+
+	/**
+		The value associated with the property. 
+		Can be any valid JavaScript value (number, object, function, etc).
+	**/
 	@:optional var value:Any;
+
+	/**
+		`true` if and only if the value associated with the property may be 
+		changed with an assignment operator.
+		
+		Defaults to `false`.
+	**/
 	@:optional var writable:Bool;
+
+	/**
+		A function which serves as a getter for the property, or `undefined` if 
+		there is no getter. When the property is accessed, this function is 
+		called without arguments and with `this` set to the object through which 
+		the property is accessed (this may not be the object on which the 
+		property is defined due to inheritance). 
+		The return value will be used as the value of the property.
+	**/
 	@:optional var get:Void->Any;
+
+	/**
+		A function which serves as a setter for the property, or undefined if
+		there is no setter. When the property is assigned to, this function 
+		is called with one argument (the value being assigned to the property)
+		and with `this` set to the object through which the property is assigned.
+	**/
 	@:optional var set:Any->Void;
 }

std/js/Promise.hx

@@ -24,30 +24,80 @@ package js;
 
 import haxe.extern.EitherType;
 
+/**
+	The Promise object represents the eventual completion (or failure) of an 
+	asynchronous operation and its resulting value.
+	
+	Documentation [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) by [Mozilla Contributors](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise$history), licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/).
+**/
 @:native("Promise")
 extern class Promise<T>
 {
+	/**
+		Returns a Promise object that is resolved with the given value. If the 
+		value is Thenable, the returned promise will "follow" that 
+		thenable, adopting its eventual state; 
+		otherwise the returned promise will be fulfilled with the value. 
+		Generally, when it's unknown when value is a promise or not, 
+		use `Promise.resolve(value)` instead and work with the return value as 
+		a promise.
+	**/
 	@:overload(function<T>(promise : Promise<T>) : Promise<T> {})
 	@:overload(function<T>(thenable : Thenable<T>) : Promise<T> {})
 	static function resolve<T>( ?value : T ) : Promise<T>;
 
+	/**
+		Returns a Promise object that is rejected with the given reason.
+	**/
 	static function reject<T>( ?reason : Dynamic ) : Promise<T>;
 
+	/**
+		Returns a promise that either fulfills when all of the promises in the 
+		iterable argument have fulfilled or rejects as soon as one of the
+		promises in the iterable argument rejects. If the returned promise 
+		fulfills, it is fulfilled with an array of the values from the 
+		fulfilled promises in the same order as defined in the iterable. 
+		If the returned promise rejects, it is rejected with the reason from 
+		the first promise in the iterable that rejected. This method can be 
+		useful for aggregating results of multiple promises.
+	**/
 	static function all( iterable : Array<Dynamic> ) : Promise<Array<Dynamic>>;
 
+	/**
+		Returns a promise that fulfills or rejects as soon as one of the 
+		promises in the iterable fulfills or rejects, with the value or reason 
+		from that promise.
+	**/
 	static function race( iterable : Array<Dynamic> ) : Promise<Dynamic>;
 
 	/** @throws DOMError */
 	function new( init : (resolve : (value : T) -> Void, reject: (reason : Dynamic) -> Void) -> Void ) : Void;
 
+	/**
+		Appends fulfillment and rejection handlers to the promise and returns a 
+		new promise resolving to the return value of the called handler, or to 
+		its original settled value if the promise was not handled 
+		(i.e. if the relevant handler onFulfilled or onRejected is not a function).
+	**/
 	function then<TOut>( fulfillCallback : Null<PromiseCallback<T, TOut>>, ?rejectCallback : EitherType<Dynamic -> Void, PromiseCallback<Dynamic, TOut>> ) : Promise<TOut>;
 
+	/**
+		Appends a rejection handler callback to the promise, and returns a new 
+		promise resolving to the return value of the callback if it is called, 
+		or to its original fulfillment value if the promise is instead fulfilled.
+	**/
 	@:native("catch")
 	function catchError<TOut>( rejectCallback : EitherType<Dynamic -> Void, PromiseCallback<Dynamic, TOut>> ) : Promise<TOut>;
 }
 
+/**
+	Callback for the Promise object.
+**/
 typedef PromiseCallback<T, TOut> = EitherType<T -> TOut, T -> Promise<TOut>>;
 
+/**
+	A value with a `then` method.
+**/
 typedef Thenable<T> = {
 	function then(resolve:T->Void, ?reject:Dynamic->Void):Void;
 }

std/js/Set.hx

@@ -23,16 +23,76 @@ package js;
 
 import js.Map.MapEntry;
 
+/**
+	The `js.Set` object lets you store unique values of any type, whether 
+	primitive values or object references.
+	
+	Documentation [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) by [Mozilla Contributors](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set$history), licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/).
+**/
 @:native("Set")
 extern class Set<T> {
+	/** 
+		The number of values in the `js.Set` object. 
+	**/
 	var size(default,null):Int;
+
+	/**
+		If an iterable object is passed, all of its elements will be added to 
+		the new `js.Set`. 
+	**/
 	@:pure function new(?iterable:Any);
+
+	/**
+		Returns a boolean asserting whether an element is present with the given
+		value in the `js.Set` object or not.
+	**/
 	@:pure function has(value:T):Bool;
+
+	/**
+		Appends a new element with the given value to the `js.Set` object. 
+		Returns the `js.Set` object.
+	**/
 	function add(value:T):Set<T>;
+
+	/**
+		Removes the element associated to the value and returns the value that
+		`has(value)` would have previously returned. 
+		`has(value)` will return `false` afterwards.
+	**/
 	function delete(value:T):Bool;
+
+	/**
+		Removes all elements from the `js.Set` object.
+	**/
 	function clear():Void;
+
+	/**
+		Calls `callback` once for each key-value pair present in the `js.Set` 
+		object, in insertion order. 
+		
+		If a `thisArg` parameter is provided to forEach, it will be used as the
+		`this` value for each callback.
+	**/
 	function forEach(callback:(value:T, key:T, set:Set<T>)->Void, ?thisArg:Any):Void;
+
+	/**
+		Returns a new `JsIterator` object that contains the keys for each element 
+		in the `js.Set` object in insertion order.
+	**/
 	function keys():JsIterator<T>;
+
+	/**
+		Returns a new `JsIterator` object that contains the values for each 
+		element in the `js.Set` object in insertion order.
+	**/
 	function values():JsIterator<T>;
+
+	/**
+		Returns a new `JsIterator` object that contains an array of 
+		`[value, value]` for each element in the `js.Set` object, in insertion 
+		order. 
+		This is kept similar to the `js.Map` object, so that each entry has the 
+		same value for its key and value here.
+	**/
 	function entries():JsIterator<MapEntry<T,T>>;
 }