doc: esm/fetchModule (and DNS.lookup)

lib/internal/dns/promises.js

@@ -154,6 +154,19 @@ function createLookupPromise(family, hostname, all, hints, verbatim) {
 }
 
 const validFamilies = [0, 4, 6];
+/**
+ * Get the IP address for a given hostname.
+ * @param {URL['hostname']} hostname - The hostname to resolve (ex. 'nodejs.org').
+ * @param {Object} [options] - Optional settings.
+ * @param {boolean} [options.all=false] - Whether to return all or just the first resolved address.
+ * @param {number} [options.family=0] - The record family. Must be 4, 6, or 0 (for both).
+ * @param {number} [options.hints] - One or more supported getaddrinfo flags (supply multiple via
+ * bitwise OR).
+ * @param {boolean} [options.verbatim=false] - Return results in same order DNS resolved them;
+ * otherwise IPv4 then IPv6. New code should supply `true`.
+ * @typedef DNSLookupResult = { address: string, family: number }
+ * @returns {Promise<DNSLookupResult | DNSLookupResult[]>}
+ */
 function lookup(hostname, options) {
   let hints = 0;
   let family = 0;

lib/internal/modules/esm/fetch_module.js

@@ -44,7 +44,17 @@ const cacheForGET = new SafeMap();
 // [2] Creating a new agent instead of using the gloabl agent improves
 // performance and precludes the agent becoming tainted.
 
+/**
+ * @type {https.Agent} The Cached HTTP Agent for **secure** HTTP requests.
+ */
 let HTTPSAgent;
+/**
+ * Make a **secure** HTTP GET request (handling agent setup if needed, caching the agent to avoid
+ * redudant instantiations).
+ * @param {URL['href']} url - The URI to fetch.
+ * @param {Object} opts - See https.get() options.
+ * @returns {http.ClientRequest}
+ */
 function HTTPSGet(url, opts) {
   const https = require('https'); // [1]
   HTTPSAgent ??= new https.Agent({ // [2]
@@ -56,7 +66,17 @@ function HTTPSGet(url, opts) {
   });
 }
 
+/**
+ * @type {http.Agent} The Cached HTTP Agent for **insecure** HTTP requests.
+ */
 let HTTPAgent;
+/**
+ * Make a **insecure** HTTP GET request (handling agent setup if needed, caching the agent to avoid
+ * redudant instantiations).
+ * @param {URL['href']} url - The URI to fetch.
+ * @param {Object} opts - See http.get() options.
+ * @returns {http.ClientRequest}
+ */
 function HTTPGet(url, opts) {
   const http = require('http'); // [1]
   HTTPAgent ??= new http.Agent({ // [2]
@@ -68,20 +88,31 @@ function HTTPGet(url, opts) {
   });
 }
 
+/**
+ * @type {import('../../dns/promises.js').lookup}
+ */
 function dnsLookup(name, opts) {
   // eslint-disable-next-line no-func-assign
   dnsLookup = require('dns/promises').lookup;
   return dnsLookup(name, opts);
 }
 
 let zlib;
+/**
+ * Create a decompressor for the Brotli format.
+ * @returns {import('../../../zlib.js').BrotliDecompress}
+ */
 function createBrotliDecompress() {
   zlib ??= require('zlib'); // [1]
   // eslint-disable-next-line no-func-assign
   createBrotliDecompress = zlib.createBrotliDecompress;
   return createBrotliDecompress();
 }
 
+/**
+ * Create an unzip handler.
+ * @returns {import('../../../zlib.js').Unzip}
+ */
 function createUnzip() {
   zlib ??= require('zlib'); // [1]
   // eslint-disable-next-line no-func-assign

lib/zlib.js

@@ -778,6 +778,10 @@ function InflateRaw(opts) {
 ObjectSetPrototypeOf(InflateRaw.prototype, Zlib.prototype);
 ObjectSetPrototypeOf(InflateRaw, Zlib);
 
+/**
+ * @typedef {Object} UnzipOptions
+ * @returns {Zlib}
+ */
 function Unzip(opts) {
   if (!(this instanceof Unzip))
     return new Unzip(opts);
@@ -862,6 +866,10 @@ function BrotliCompress(opts) {
 ObjectSetPrototypeOf(BrotliCompress.prototype, Brotli.prototype);
 ObjectSetPrototypeOf(BrotliCompress, Brotli);
 
+/**
+ * @typedef {Object} BrotliOptions
+ * @returns {Brotli}
+ */
 function BrotliDecompress(opts) {
   if (!(this instanceof BrotliDecompress))
     return new BrotliDecompress(opts);