typings: add JSDoc typings for https

Added JSDoc typings for the `https` lib module.

PR-URL: https://github.com/nodejs/node/pull/38589
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>

1 files changed, 71 insertions, 1 deletions

diff --git a/lib/https.js b/lib/https.js
index 080efe40faa..765e1a22b60 100644
--- a/lib/https.js
+++ b/lib/https.js
@@ -94,6 +94,17 @@ ObjectSetPrototypeOf(Server, tls.Server);
 
 Server.prototype.setTimeout = HttpServer.prototype.setTimeout;
 
+/**
+ * Creates a new `https.Server` instance.
+ * @param {{
+ *   IncomingMessage?: IncomingMessage;
+ *   ServerResponse?: ServerResponse;
+ *   insecureHTTPParser?: boolean;
+ *   maxHeaderSize?: number;
+ *   }} [opts]
+ * @param {Function} [requestListener]
+ * @returns {Server}
+ */
 function createServer(opts, requestListener) {
   return new Server(opts, requestListener);
 }
@@ -151,7 +162,21 @@ function createConnection(port, host, options) {
   return socket;
 }
 
-
+/**
+ * Creates a new `HttpAgent` instance.
+ * @param {{
+ *   keepAlive?: boolean;
+ *   keepAliveMsecs?: number;
+ *   maxSockets?: number;
+ *   maxTotalSockets?: number;
+ *   maxFreeSockets?: number;
+ *   scheduling?: string;
+ *   timeout?: number;
+ *   maxCachedSessions?: number;
+ *   servername?: string;
+ *   }} [options]
+ * @returns {Agent}
+ */
 function Agent(options) {
   if (!(this instanceof Agent))
     return new Agent(options);
@@ -172,6 +197,16 @@ ObjectSetPrototypeOf(Agent.prototype, HttpAgent.prototype);
 ObjectSetPrototypeOf(Agent, HttpAgent);
 Agent.prototype.createConnection = createConnection;
 
+/**
+ * Gets a unique name for a set of options.
+ * @param {{
+ *   host: string;
+ *   port: number;
+ *   localAddress: string;
+ *   family: number;
+ *   }} [options]
+ * @returns {string}
+ */
 Agent.prototype.getName = function getName(options) {
   let name = FunctionPrototypeCall(HttpAgent.prototype.getName, this, options);
 
@@ -295,6 +330,11 @@ Agent.prototype._evictSession = function _evictSession(key) {
 
 const globalAgent = new Agent();
 
+/**
+ * Makes a request to a secure web server.
+ * @param {...any} args
+ * @returns {ClientRequest}
+ */
 function request(...args) {
   let options = {};
 
@@ -317,6 +357,36 @@ function request(...args) {
   return ReflectConstruct(ClientRequest, args);
 }
 
+/**
+ * Makes a GET request to a secure web server.
+ * @param {string | URL} input
+ * @param {{
+ *   agent?: Agent | boolean;
+ *   auth?: string;
+ *   createConnection?: Function;
+ *   defaultPort?: number;
+ *   family?: number;
+ *   headers?: Object;
+ *   hints?: number;
+ *   host?: string;
+ *   hostname?: string;
+ *   insecureHTTPParser?: boolean;
+ *   localAddress?: string;
+ *   localPort?: number;
+ *   lookup?: Function;
+ *   maxHeaderSize?: number;
+ *   method?: string;
+ *   path?: string;
+ *   port?: number;
+ *   protocol?: string;
+ *   setHost?: boolean;
+ *   socketPath?: string;
+ *   timeout?: number;
+ *   signal?: AbortSignal;
+ *   } | string | URL} [options]
+ * @param {Function} [cb]
+ * @returns {ClientRequest}
+ */
 function get(input, options, cb) {
   const req = request(input, options, cb);
   req.end();