Added documentation to builtins/array

boa/src/builtins/array/mod.rs

@@ -1,3 +1,14 @@
+//! This module implements the global `Array` object.
+//!
+//! The JavaScript `Array` class is a global object that is used in the construction of arrays; which are high-level, list-like objects.
+//!
+//! More information:
+//!  - [ECMAScript reference][spec]
+//!  - [MDN documentation][mdn]
+//!
+//! [spec]: https://tc39.es/ecma262/#sec-array-objects
+//! [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
+
 #[cfg(test)]
 mod tests;
 
@@ -14,6 +25,7 @@ use gc::Gc;
 use std::borrow::Borrow;
 use std::cmp::{max, min};
 
+/// Creates a new `Array` instance.
 pub(crate) fn new_array(interpreter: &Interpreter) -> ResultValue {
     let array = ValueData::new_obj(Some(
         &interpreter
@@ -120,8 +132,13 @@ pub fn make_array(this: &Value, args: &[Value], ctx: &mut Interpreter) -> Result
 ///
 /// The isArray function takes one argument arg, and returns the Boolean value true
 /// if the argument is an object whose class internal property is "Array"; otherwise it returns false.
-/// <https://tc39.es/ecma262/#sec-array.isarray>
+///
-/// ECMA-262 v5, 15.4.3.2
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.isarray
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray
 pub fn is_array(_this: &Value, args: &[Value], _interpreter: &mut Interpreter) -> ResultValue {
     let value_true = Gc::new(ValueData::Boolean(true));
     let value_false = Gc::new(ValueData::Boolean(false));
@@ -150,7 +167,13 @@ pub fn is_array(_this: &Value, args: &[Value], _interpreter: &mut Interpreter) -
 /// When the concat method is called with zero or more arguments, it returns an
 /// array containing the array elements of the object followed by the array
 /// elements of each argument in order.
-/// <https://tc39.es/ecma262/#sec-array.prototype.concat>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.concat
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat
 pub fn concat(this: &Value, args: &[Value], _: &mut Interpreter) -> ResultValue {
     if args.is_empty() {
         // If concat is called with no arguments, it returns the original array
@@ -183,7 +206,13 @@ pub fn concat(this: &Value, args: &[Value], _: &mut Interpreter) -> ResultValue
 /// The arguments are appended to the end of the array, in the order in which
 /// they appear. The new length of the array is returned as the result of the
 /// call.
-/// <https://tc39.es/ecma262/#sec-array.prototype.push>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.push
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push
 pub fn push(this: &Value, args: &[Value], _: &mut Interpreter) -> ResultValue {
     let new_array = add_to_array_object(this, args)?;
     Ok(new_array.get_field_slice("length"))
@@ -192,7 +221,13 @@ pub fn push(this: &Value, args: &[Value], _: &mut Interpreter) -> ResultValue {
 /// Array.prototype.pop ( )
 ///
 /// The last element of the array is removed from the array and returned.
-/// <https://tc39.es/ecma262/#sec-array.prototype.pop>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.pop
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/pop
 pub fn pop(this: &Value, _: &[Value], _: &mut Interpreter) -> ResultValue {
     let curr_length: i32 =
         from_value(this.get_field_slice("length")).expect("Could not convert argument to i32");
@@ -209,7 +244,13 @@ pub fn pop(this: &Value, _: &[Value], _: &mut Interpreter) -> ResultValue {
 /// Array.prototype.forEach ( callbackFn [ , thisArg ] )
 ///
 /// This method executes the provided callback function for each element in the array.
-/// <https://tc39.es/ecma262/#sec-array.prototype.foreach>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.foreach
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach
 pub fn for_each(this: &Value, args: &[Value], interpreter: &mut Interpreter) -> ResultValue {
     if args.is_empty() {
         return Err(to_value(
@@ -238,7 +279,13 @@ pub fn for_each(this: &Value, args: &[Value], interpreter: &mut Interpreter) ->
 /// The elements of the array are converted to Strings, and these Strings are
 /// then concatenated, separated by occurrences of the separator. If no
 /// separator is provided, a single comma is used as the separator.
-/// <https://tc39.es/ecma262/#sec-array.prototype.join>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.join
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/join
 pub fn join(this: &Value, args: &[Value], _: &mut Interpreter) -> ResultValue {
     let separator = if args.is_empty() {
         String::from(",")
@@ -262,7 +309,13 @@ pub fn join(this: &Value, args: &[Value], _: &mut Interpreter) -> ResultValue {
 /// The toString function is intentionally generic; it does not require that
 /// its this value be an Array object. Therefore it can be transferred to
 /// other kinds of objects for use as a method.
-/// <https://tc39.es/ecma262/#sec-array.prototype.tostring>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.tostring
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toString
 pub fn to_string(this: &Value, _args: &[Value], _ctx: &mut Interpreter) -> ResultValue {
     let method_name = "join";
     let mut arguments = vec![to_value(",")];
@@ -297,7 +350,13 @@ pub fn to_string(this: &Value, _args: &[Value], _ctx: &mut Interpreter) -> Resul
 ///
 /// The elements of the array are rearranged so as to reverse their order.
 /// The object is returned as the result of the call.
-/// <https://tc39.es/ecma262/#sec-array.prototype.reverse/>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.reverse
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse
 #[allow(clippy::else_if_without_else)]
 pub fn reverse(this: &Value, _: &[Value], _: &mut Interpreter) -> ResultValue {
     let len: i32 =
@@ -331,7 +390,13 @@ pub fn reverse(this: &Value, _: &[Value], _: &mut Interpreter) -> ResultValue {
 /// Array.prototype.shift ( )
 ///
 /// The first element of the array is removed from the array and returned.
-/// <https://tc39.es/ecma262/#sec-array.prototype.shift/>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.shift
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/shift
 pub fn shift(this: &Value, _: &[Value], _: &mut Interpreter) -> ResultValue {
     let len: i32 =
         from_value(this.get_field_slice("length")).expect("Could not convert argument to i32");
@@ -368,7 +433,13 @@ pub fn shift(this: &Value, _: &[Value], _: &mut Interpreter) -> ResultValue {
 /// The arguments are prepended to the start of the array, such that their order
 /// within the array is the same as the order in which they appear in the
 /// argument list.
-/// <https://tc39.es/ecma262/#sec-array.prototype.unshift/>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.unshift
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/unshift
 pub fn unshift(this: &Value, args: &[Value], _: &mut Interpreter) -> ResultValue {
     let len: i32 =
         from_value(this.get_field_slice("length")).expect("Could not convert argument to i32");
@@ -407,7 +478,13 @@ pub fn unshift(this: &Value, args: &[Value], _: &mut Interpreter) -> ResultValue
 /// element present in the array until it finds the one where callback returns
 /// a falsy value. It returns `false` if it finds such element, otherwise it
 /// returns `true`.
-/// <https://tc39.es/ecma262/#sec-array.prototype.every/>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.every
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every
 pub fn every(this: &Value, args: &[Value], interpreter: &mut Interpreter) -> ResultValue {
     if args.is_empty() {
         return Err(to_value(
@@ -440,7 +517,13 @@ pub fn every(this: &Value, args: &[Value], interpreter: &mut Interpreter) -> Res
 ///
 /// For each element in the array the callback function is called, and a new
 /// array is constructed from the return values of these calls.
-/// <https://tc39.es/ecma262/#sec-array.prototype.map>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.map
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map
 pub fn map(this: &Value, args: &[Value], interpreter: &mut Interpreter) -> ResultValue {
     if args.is_empty() {
         return Err(to_value(
@@ -483,7 +566,13 @@ pub fn map(this: &Value, args: &[Value], interpreter: &mut Interpreter) -> Resul
 /// i.e. the array will not be searched. If it is negative, it is used as the offset
 /// from the end of the array to compute fromIndex. If the computed index is less than 0,
 /// the whole array will be searched.
-/// <https://tc39.es/ecma262/#sec-array.prototype.indexof>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.indexof
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf
 pub fn index_of(this: &Value, args: &[Value], _: &mut Interpreter) -> ResultValue {
     // If no arguments, return -1. Not described in spec, but is what chrome does.
     if args.is_empty() {
@@ -532,7 +621,13 @@ pub fn index_of(this: &Value, args: &[Value], _: &mut Interpreter) -> ResultValu
 /// (i.e. the whole array is searched). If it is greater than or equal to the length of the array,
 /// the whole array will be searched. If it is negative, it is used as the offset from the end
 /// of the array to compute fromIndex. If the computed index is less than 0, -1 is returned.
-/// <https://tc39.es/ecma262/#sec-array.prototype.lastindexof>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.lastindexof
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/lastIndexOf
 pub fn last_index_of(this: &Value, args: &[Value], _: &mut Interpreter) -> ResultValue {
     // If no arguments, return -1. Not described in spec, but is what chrome does.
     if args.is_empty() {
@@ -575,7 +670,13 @@ pub fn last_index_of(this: &Value, args: &[Value], _: &mut Interpreter) -> Resul
 /// The find method executes the callback function once for each index of the array
 /// until the callback returns a truthy value. If so, find immediately returns the value
 /// of that element. Otherwise, find returns undefined.
-/// <https://tc39.es/ecma262/#sec-array.prototype.find>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.find
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find
 pub fn find(this: &Value, args: &[Value], interpreter: &mut Interpreter) -> ResultValue {
     if args.is_empty() {
         return Err(to_value(
@@ -605,7 +706,13 @@ pub fn find(this: &Value, args: &[Value], interpreter: &mut Interpreter) -> Resu
 /// This method executes the provided predicate function for each element of the array.
 /// If the predicate function returns `true` for an element, this method returns the index of the element.
 /// If all elements return `false`, the value `-1` is returned.
-/// <https://tc39.es/ecma262/#sec-array.prototype.findindex/>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.findindex
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex
 pub fn find_index(this: &Value, args: &[Value], interpreter: &mut Interpreter) -> ResultValue {
     if args.is_empty() {
         return Err(to_value(
@@ -640,8 +747,14 @@ pub fn find_index(this: &Value, args: &[Value], interpreter: &mut Interpreter) -
 /// Array.prototype.fill ( value[, start[, end]] )
 ///
 /// The method fills (modifies) all the elements of an array from start index (default 0)
-/// to an end index (default array length) with a static value. It returns the modified array
+/// to an end index (default array length) with a static value. It returns the modified array.
-/// <https://tc39.es/ecma262/#sec-array.prototype.fill>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.fill
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill
 pub fn fill(this: &Value, args: &[Value], _: &mut Interpreter) -> ResultValue {
     let len: i32 = from_value(this.get_field_slice("length")).expect("Could not get argument");
     let default_value = undefined();
@@ -671,6 +784,16 @@ pub fn fill(this: &Value, args: &[Value], _: &mut Interpreter) -> ResultValue {
     Ok(this.clone())
 }
 
+/// Array.prototype.includes( valueToFind [, fromIndex] )
+///
+/// Determines whether an array includes a certain value among its entries, returning `true` or `false` as appropriate.
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.includes
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes
 pub fn includes_value(this: &Value, args: &[Value], _: &mut Interpreter) -> ResultValue {
     let search_element = args
         .get(0)
@@ -698,7 +821,13 @@ pub fn includes_value(this: &Value, args: &[Value], _: &mut Interpreter) -> Resu
 /// end of the array if end is undefined). If start is negative, it is treated as length + start
 /// where length is the length of the array. If end is negative, it is treated as length + end where
 /// length is the length of the array.
-/// <https://tc39.es/ecma262/#sec-array.prototype.slice>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.slice
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice
 pub fn slice(this: &Value, args: &[Value], interpreter: &mut Interpreter) -> ResultValue {
     let new_array = new_array(interpreter)?;
     let len: i32 =
@@ -740,8 +869,14 @@ pub fn slice(this: &Value, args: &[Value], interpreter: &mut Interpreter) -> Res
 /// Array.prototype.filter ( callback, [ thisArg ] )
 ///
 /// For each element in the array the callback function is called, and a new
-/// array is constructed for every value whose callback returned a truthy value
+/// array is constructed for every value whose callback returned a truthy value.
-/// <https://tc39.es/ecma262/#sec-array.prototype.filter>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.filter
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter
 pub fn filter(this: &Value, args: &[Value], interpreter: &mut Interpreter) -> ResultValue {
     if args.is_empty() {
         return Err(to_value(
@@ -786,7 +921,13 @@ pub fn filter(this: &Value, args: &[Value], interpreter: &mut Interpreter) -> Re
 /// in the array. Otherwise, false.
 ///
 /// Caution: Calling this method on an empty array returns false for any condition!
-/// <https://tc39.es/ecma262/#sec-array.prototype.some/>
+///
+/// More information:
+///  - [ECMAScript reference][spec]
+///  - [MDN documentation][mdn]
+///
+/// [spec]: https://tc39.es/ecma262/#sec-array.prototype.some
+/// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some
 pub fn some(this: &Value, args: &[Value], interpreter: &mut Interpreter) -> ResultValue {
     if args.is_empty() {
         return Err(to_value(
@@ -816,7 +957,7 @@ pub fn some(this: &Value, args: &[Value], interpreter: &mut Interpreter) -> Resu
     Ok(to_value(false))
 }
 
-/// Create a new `Array` object
+/// Create a new `Array` object.
 pub fn create_constructor(global: &Value) -> Value {
     // Create Constructor
     let object_prototype = global.get_field_slice("Object").get_field_slice(PROTOTYPE);

boa/src/builtins/mod.rs

@@ -13,7 +13,6 @@ macro_rules! make_builtin_fn {
     };
 }
 
-/// The global `Array` object
 pub mod array;
 /// The global `Boolean` object
 pub mod boolean;