typings: add JSDoc typings for https

VoltrexKeyva · richardlau · commit 58154ce42615 · 2021-07-20T07:11:21.000-04:00
Added JSDoc typings for the `https` lib module. PR-URL: #38589 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>
diff --git a/lib/https.js b/lib/https.js
@@ -95,6 +95,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);
 }
@@ -152,7 +163,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);
@@ -173,6 +198,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);
 
@@ -297,6 +332,12 @@ Agent.prototype._evictSession = function _evictSession(key) {
 const globalAgent = new Agent();
 
 let urlWarningEmitted = false;
+
+/**
+ * Makes a request to a secure web server.
+ * @param {...any} args
+ * @returns {ClientRequest}
+ */
 function request(...args) {
   let options = {};
 
@@ -333,6 +374,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();
