fix: fix docs gap

Author: uhyo

lib/lib.es2015.collection.d.ts

@@ -1,4 +1,7 @@
 interface Map<K, V> {
+  /**
+   * Executes a provided function once per each key/value pair in the Map, in insertion order.
+   */
   forEach<This = undefined>(
     callbackfn: (this: This, value: V, key: K, map: this) => void,
     thisArg?: This
@@ -25,6 +28,9 @@ interface ReadonlyMap<K, V> {
 }
 
 interface Set<T> {
+  /**
+   * Executes a provided function once per each value in the Set object, in insertion order.
+   */
   forEach<This = undefined>(
     callbackfn: (this: This, value: T, value2: T, set: this) => void,
     thisArg?: This

lib/lib.es2015.iterable.d.ts

@@ -11,19 +11,19 @@ interface IterableIterator<T> extends Iterator<T, undefined, void> {
 
 interface ArrayConstructor {
   /**
-   * Creates an array from an array-like or iterable object.
-   * @param source An array-like or iterable object to convert to an array.
+   * Creates an array from an iterable object.
+   * @param iterable An iterable object to convert to an array.
    */
-  from<T>(source: Iterable<T> | ArrayLike<T>): T[];
+  from<T>(iterable: Iterable<T> | ArrayLike<T>): T[];
 
   /**
-   * Creates an array from an array-like or iterable object.
-   * @param source An array-like or iterable object to convert to an array.
+   * Creates an array from an iterable object.
+   * @param iterable An iterable object to convert to an array.
    * @param mapfn A mapping function to call on every element of the array.
    * @param thisArg Value of 'this' used to invoke the mapfn.
    */
   from<T, U, This = undefined>(
-    source: Iterable<T> | ArrayLike<T>,
+    iterable: Iterable<T> | ArrayLike<T>,
     mapfn: (this: This, v: T, k: number) => U,
     thisArg?: This
   ): U[];
@@ -58,18 +58,18 @@ interface MapConstructor {
 
 interface TypedNumberArrayConstructor {
   /**
-   * Creates an array from an array-like or iterable object.
-   * @param source An array-like or iterable object to convert to an array.
+   * Creates an array from an iterable object.
+   * @param iterable An iterable object to convert to an array.
    */
-  from(source: Iterable<number> | ArrayLike<number>): TypedNumberArray;
+  from(iterable: Iterable<number> | ArrayLike<number>): TypedNumberArray;
   /**
-   * Creates an array from an array-like or iterable object.
-   * @param source An array-like or iterable object to convert to an array.
+   * Creates an array from an iterable object.
+   * @param iterable An iterable object to convert to an array.
    * @param mapfn A mapping function to call on every element of the array.
    * @param thisArg Value of 'this' used to invoke the mapfn.
    */
   from<T, This = undefined>(
-    source: Iterable<T> | ArrayLike<T>,
+    iterable: Iterable<T> | ArrayLike<T>,
     mapfn: (this: This, v: T, k: number) => number,
     thisArg?: This
   ): TypedNumberArray;

lib/lib.es2015.proxy.d.ts

@@ -1,20 +1,28 @@
 interface ProxyHandler<T extends object> {
+  /**
+   * A trap method for a function call.
+   * @param target The original callable object which is being proxied.
+   */
   apply?(target: T, thisArg: unknown, argArray: unknown[]): any;
+  /**
+   * A trap for the `new` operator.
+   * @param target The original object which is being proxied.
+   * @param newTarget The constructor that was originally called.
+   */
   construct?(target: T, argArray: unknown[], newTarget: unknown): object;
-  defineProperty?(
-    target: T,
-    p: PropertyKey,
-    attributes: PropertyDescriptor
-  ): boolean;
-  deleteProperty?(target: T, p: PropertyKey): boolean;
-  get?(target: T, p: PropertyKey, receiver: unknown): any;
-  getOwnPropertyDescriptor?(
-    target: T,
-    p: PropertyKey
-  ): PropertyDescriptor | undefined;
-  getPrototypeOf?(target: T): object | null;
-  has?(target: T, p: PropertyKey): boolean;
-  ownKeys?(target: T): PropertyKey[];
-  set?(target: T, p: PropertyKey, value: unknown, receiver: unknown): boolean;
-  setPrototypeOf?(target: T, v: unknown): boolean;
+  /**
+   * A trap for getting a property value.
+   * @param target The original object which is being proxied.
+   * @param p The name or `Symbol` of the property to get.
+   * @param receiver The proxy or an object that inherits from the proxy.
+   */
+  get?(target: T, p: string | symbol, receiver: unknown): any;
+   /**
+   * A trap for setting a property value.
+   * @param target The original object which is being proxied.
+   * @param p The name or `Symbol` of the property to set.
+   * @param receiver The object to which the assignment was originally directed.
+   * @returns A `Boolean` indicating whether or not the property was set.
+   */
+  set?(target: T, p: string | symbol, value: unknown, receiver: unknown): boolean;
 }

lib/lib.es2015.reflect.d.ts

@@ -1,127 +1,14 @@
 declare namespace Reflect {
-  /**
-   * Calls the function with the specified object as the this value
-   * and the elements of specified array as the arguments.
-   * @param target The function to call.
-   * @param thisArgument The object to be used as the this object.
-   * @param argumentsList An array of argument values to be passed to the function.
-   */
-  function apply(
-    target: Function,
-    thisArgument: any,
-    argumentsList: ArrayLike<any>
-  ): unknown;
-
-  /**
-   * Constructs the target with the elements of specified array as the arguments
-   * and the specified constructor as the `new.target` value.
-   * @param target The constructor to invoke.
-   * @param argumentsList An array of argument values to be passed to the constructor.
-   * @param newTarget The constructor to be used as the `new.target` object.
-   */
-  function construct(
-    target: Function,
-    argumentsList: ArrayLike<any>,
-    newTarget?: any
-  ): object;
-
-  /**
-   * Adds a property to an object, or modifies attributes of an existing property.
-   * @param target Object on which to add or modify the property. This can be a native JavaScript object
-   *        (that is, a user-defined object or a built in object) or a DOM object.
-   * @param propertyKey The property name.
-   * @param attributes Descriptor for the property. It can be for a data property or an accessor property.
-   */
-  function defineProperty(
-    target: object,
-    propertyKey: PropertyKey,
-    attributes: PropertyDescriptor
-  ): boolean;
-
-  /**
-   * Removes a property from an object, equivalent to `delete target[propertyKey]`,
-   * except it won't throw if `target[propertyKey]` is non-configurable.
-   * @param target Object from which to remove the own property.
-   * @param propertyKey The property name.
-   */
-  function deleteProperty(target: object, propertyKey: PropertyKey): boolean;
-
   /**
    * Gets the property of target, equivalent to `target[propertyKey]` when `receiver === target`.
    * @param target Object that contains the property on itself or in its prototype chain.
    * @param propertyKey The property name.
    * @param receiver The reference to use as the `this` value in the getter function,
    *        if `target[propertyKey]` is an accessor property.
    */
-  function get<T, K extends PropertyKey>(
+  function get<T, P extends PropertyKey>(
     target: T,
-    propertyKey: K,
-    receiver?: any
-  ): K extends keyof T ? T[K] : unknown;
-
-  /**
-   * Gets the own property descriptor of the specified object.
-   * An own property descriptor is one that is defined directly on the object and is not inherited from the object's prototype.
-   * @param target Object that contains the property.
-   * @param propertyKey The property name.
-   */
-  function getOwnPropertyDescriptor(
-    target: object,
-    propertyKey: PropertyKey
-  ): PropertyDescriptor | undefined;
-
-  /**
-   * Returns the prototype of an object.
-   * @param target The object that references the prototype.
-   */
-  function getPrototypeOf(target: object): object;
-
-  /**
-   * Equivalent to `propertyKey in target`.
-   * @param target Object that contains the property on itself or in its prototype chain.
-   * @param propertyKey Name of the property.
-   */
-  function has(target: object, propertyKey: PropertyKey): boolean;
-
-  /**
-   * Returns a value that indicates whether new properties can be added to an object.
-   * @param target Object to test.
-   */
-  function isExtensible(target: object): boolean;
-
-  /**
-   * Returns the string and symbol keys of the own properties of an object. The own properties of an object
-   * are those that are defined directly on that object, and are not inherited from the object's prototype.
-   * @param target Object that contains the own properties.
-   */
-  function ownKeys(target: object): PropertyKey[];
-
-  /**
-   * Prevents the addition of new properties to an object.
-   * @param target Object to make non-extensible.
-   * @return Whether the object has been made non-extensible.
-   */
-  function preventExtensions(target: object): boolean;
-
-  /**
-   * Sets the property of target, equivalent to `target[propertyKey] = value` when `receiver === target`.
-   * @param target Object that contains the property on itself or in its prototype chain.
-   * @param propertyKey Name of the property.
-   * @param receiver The reference to use as the `this` value in the setter function,
-   *        if `target[propertyKey]` is an accessor property.
-   */
-  function set(
-    target: object,
-    propertyKey: PropertyKey,
-    value: any,
-    receiver?: any
-  ): boolean;
-
-  /**
-   * Sets the prototype of a specified object o to object proto or null.
-   * @param target The object to change its prototype.
-   * @param proto The value of the new prototype or null.
-   * @return Whether setting the prototype was successful.
-   */
-  function setPrototypeOf(target: object, proto: any): boolean;
+    propertyKey: P,
+    receiver?: unknown
+  ): P extends keyof T ? T[P] : unknown;
 }

lib/lib.es2015.symbol.wellknown.d.ts

@@ -35,9 +35,9 @@ interface RegExp {
 
 interface String {
   /**
-   * Replaces first match with string or all matches with RegExp.
-   * @param searchValue A object can search for and replace matches within a string.
-   * @param replaceValue A string containing the text to replace for match.
+   * Passes a string and {@linkcode replaceValue} to the `[Symbol.replace]` method on {@linkcode searchValue}. This method is expected to implement its own replacement algorithm.
+   * @param searchValue An object that supports searching for and replacing matches within a string.
+   * @param replaceValue The replacement text.
    */
   replace(
     searchValue: {

lib/lib.es5.d.ts

@@ -773,17 +773,17 @@ interface TypedNumberArray {
 interface TypedNumberArrayConstructor {
   /**
    * Creates an array from an array-like or iterable object.
-   * @param source An array-like or iterable object to convert to an array.
+   * @param arrayLike An array-like or iterable object to convert to an array.
    */
-  from(source: ArrayLike<number>): TypedNumberArray;
+  from(arrayLike: ArrayLike<number>): TypedNumberArray;
   /**
    * Creates an array from an array-like or iterable object.
-   * @param source An array-like or iterable object to convert to an array.
+   * @param arrayLike An array-like or iterable object to convert to an array.
    * @param mapfn A mapping function to call on every element of the array.
    * @param thisArg Value of 'this' used to invoke the mapfn.
    */
   from<T, This = undefined>(
-    source: ArrayLike<T>,
+    arrayLike: ArrayLike<T>,
     mapfn: (this: This, v: T, k: number) => number,
     thisArg?: This
   ): TypedNumberArray;