From d97787fccc18ec8023c7571a38c0e13f3837df4f Mon Sep 17 00:00:00 2001
From: David Brownman <beamneocube@gmail.com>
Date: Sun, 11 Apr 2021 00:54:28 -0500
Subject: [PATCH] typings: add JSDoc to os module functions

PR-URL: /~https://github.com/nodejs/node/pull/38197
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
---
 lib/os.js | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/lib/os.js b/lib/os.js
index 19f784fc2667b2..7e23110b3085ae 100644
--- a/lib/os.js
+++ b/lib/os.js
@@ -80,8 +80,17 @@ const {
 const getHomeDirectory = getCheckedFunction(_getHomeDirectory);
 const getHostname = getCheckedFunction(_getHostname);
 const getInterfaceAddresses = getCheckedFunction(_getInterfaceAddresses);
+/**
+ * @returns {string}
+ */
 const getOSRelease = () => release;
+/**
+ * @returns {string}
+ */
 const getOSType = () => type;
+/**
+ * @returns {string}
+ */
 const getOSVersion = () => version;
 
 getFreeMem[SymbolToPrimitive] = () => getFreeMem();
@@ -97,11 +106,30 @@ const kEndianness = isBigEndian ? 'BE' : 'LE';
 
 const avgValues = new Float64Array(3);
 
+/**
+ * @returns {[number, number, number]}
+ */
 function loadavg() {
   getLoadAvg(avgValues);
   return [avgValues[0], avgValues[1], avgValues[2]];
 }
 
+/**
+ * Returns an array of objects containing information about each
+ * logical CPU core.
+ *
+ * @returns {Array<{
+ *  model: string
+ *  speed: number
+ *  times: {
+ *    user: number
+ *    nice: number
+ *    sys: number
+ *    idle: number
+ *    irq: number
+ *  }
+ * }>}
+ */
 function cpus() {
   // [] is a bugfix for a regression introduced in 51cea61
   const data = getCPUs() || [];
@@ -123,16 +151,25 @@ function cpus() {
   return result;
 }
 
+/**
+ * @returns {string}
+ */
 function arch() {
   return process.arch;
 }
 arch[SymbolToPrimitive] = () => process.arch;
 
+/**
+ * @returns {string}
+ */
 function platform() {
   return process.platform;
 }
 platform[SymbolToPrimitive] = () => process.platform;
 
+/**
+ * @returns {string}
+ */
 function tmpdir() {
   var path;
   if (isWindows) {
@@ -155,6 +192,9 @@ function tmpdir() {
 }
 tmpdir[SymbolToPrimitive] = () => tmpdir();
 
+/**
+ * @returns {'BE' | 'LE'}
+ */
 function endianness() {
   return kEndianness;
 }
@@ -204,6 +244,17 @@ function getCIDR(address, netmask, family) {
   return `${address}/${ones}`;
 }
 
+/**
+ * @returns {Record<string, Array<{
+ *  address: string
+ *  netmask: string
+ *  family: 'IPv4' | 'IPv6'
+ *  mac: string
+ *  internal: boolean
+ *  scopeid: number
+ *  cidr: string | null
+ * }>>}
+ */
 function networkInterfaces() {
   const data = getInterfaceAddresses();
   const result = {};
@@ -234,6 +285,11 @@ function networkInterfaces() {
   return result;
 }
 
+/**
+ * @param {number} pid
+ * @param {number} priority
+ * @returns {void}
+ */
 function setPriority(pid, priority) {
   if (priority === undefined) {
     priority = pid;
@@ -249,6 +305,10 @@ function setPriority(pid, priority) {
     throw new ERR_SYSTEM_ERROR(ctx);
 }
 
+/**
+ * @param {number} pid
+ * @returns {number}
+ */
 function getPriority(pid) {
   if (pid === undefined)
     pid = 0;
@@ -264,6 +324,18 @@ function getPriority(pid) {
   return priority;
 }
 
+/**
+ * @param {{ encoding?: string }} options If `encoding` is set to `'buffer'`,
+ * the `username`, `shell`, and `homedir` values will be `Buffer` instances.
+ * Default: `'utf8'`
+ * @returns {{
+ *   uid: number
+ *   gid: number
+ *   username: string
+ *   homedir: string
+ *   shell: string | null
+ * }}
+ */
 function userInfo(options) {
   if (typeof options !== 'object')
     options = null;