lib: improve comments

Author: owl-from-hogvarts

lib/find-python.js

@@ -288,7 +288,9 @@ class PythonFinder {
           )}" to get Python executable path`
         )
 
-        const result = await check.checkFunc.apply(this, [check ? check.arg : null])
+        const result = await check.checkFunc.apply(this, [
+          check ? check.arg : null
+        ])
         fail = false
         this.succeed(result.path, result.version)
 
@@ -324,7 +326,10 @@ class PythonFinder {
     }
 
     return new Promise((resolve, reject) => {
-      this.run(exec, args, shell).then(this.checkExecPath).then(resolve).catch(reject)
+      this.run(exec, args, shell)
+        .then(this.checkExecPath)
+        .then(resolve)
+        .catch(reject)
     })
   }
 
@@ -361,6 +366,7 @@ class PythonFinder {
     // to pass both path and version
     return new Promise((resolve, reject) => {
       this.log.verbose(`- executing "${execPath}" to get version`)
+
       this.run(execPath, this.argsVersion, false)
         .then((ver) => {
           // ? may be better code for version check
@@ -392,9 +398,11 @@ class PythonFinder {
               colorizeOutput(RED, 'THIS VERSION OF PYTHON IS NOT SUPPORTED')
             )
             // object with error passed for conveniences
-            // (becouse we can also pass stderr or some additional staff)
+            // (becouse we may want to pass also stderr or some additional stuff)
             // eslint-disable-next-line prefer-promise-reject-errors
-            reject({ err: new Error(`Found unsupported Python version ${ver}`) })
+            reject({
+              err: new Error(`Found unsupported Python version ${ver}`)
+            })
           }
 
           resolve({ path: execPath, version: ver })
@@ -422,6 +430,7 @@ class PythonFinder {
       function (resolve, reject) {
         const env = extend({}, this.env)
         env.TERM = 'dumb'
+        /** @type cp.ExecFileOptionsWithStringEncoding */
         const opts = { env: env, shell: shell }
 
         this.log.verbose(
@@ -434,24 +443,27 @@ class PythonFinder {
         )
         this.log.silly('execFile: opts = ', JSON.stringify(opts, null, 2))
 
-        //* assume that user use utf8 compatible termnal
-
-        //* prosible outcomes with error messages (err.message, error.stack, stderr)
-        //! on windows:
+        //* prosible outcomes with error messages on windows (err.message, error.stack?, stderr)
         // issue of encoding (garbage in terminal ) when 866 or any other locale code
         // page is setted
         // possible solutions:
-        // use "cmd" command with flag "/U" and "/C" (for more informatiom help cmd)
+        // 1. let it be as it is and just warn user that it should use utf8
+        // (already done in this.catchErros's info statement)
+        // 2. somehow determine user's terminal encdoing and use utils.TextDecoder
+        // with getting raw buffer from execFile.
+        // Requires to correct error.message becouse garbage persists there
+        // 3. Forse user's terminal to use utf8 encoding via e.g. run "chcp 65001". May broke some user's programs
+        // 4. use "cmd" command with flag "/U" and "/C" (for more informatiom run "help cmd")
         // which "Causes the output of
-        // internal commands to a pipe or file to be Unicode" (utf16le)
-        //* note: find-python-script.py send output in utf8 then may become necessary
-        //* to reencoded string with Buffer.from(stderr).toString() or something
+        // internal commands ... to be Unicode" (utf16le)
+        //* note: find-python-script.py already send output in utf8 then may become necessary
+        //* to reencode string with Buffer.from(stderr).toString() or something
         //* similar (if needed)
-        // for this solution all args should be passed as SINGLE string in quotes
-        // becouse cmd has such signature: CMD [/A | /U] [/Q] [/D] [/E:ON | /E:OFF]
-        // [/F:ON | /F:OFF] [/V:ON | /V:OFF] [[/S] [/C | /K] string]
+        // for this solution all execFile call should look like execFile("cmd /U /C", [command to run, arg1, arg2, ...])
         //* all pathes/commands and each argument must be in quotes becouse if they have
-        //* spaces they will broke everything
+        //* spaces inside they will broke everything
+
+        //* assume that user use utf8 compatible terminal
         this.execFile(exec, args, opts, execFileCallback.bind(this))
 
         /**
@@ -470,7 +482,7 @@ class PythonFinder {
           if (err || stderr) {
             reject({ err: err || null, stderr: stderr || null })
           } else {
-            // trim function removing endings which couse bugs when comparing strings
+            // trim() function remove string endings that break string comparsion
             const stdoutTrimed = stdout.trim()
             resolve(stdoutTrimed)
           }
@@ -526,7 +538,9 @@ class PythonFinder {
       this.log.silly(err ? err.stack : '')
 
       if (stderr) {
-        this.addLog(`${colorizeOutput(RED, 'STDERR:')} ${stderr ? stderr.trim() : ''}`)
+        this.addLog(
+          `${colorizeOutput(RED, 'STDERR:')} ${stderr ? stderr.trim() : ''}`
+        )
       }
     }
     this.addLog('--------------------------------------------')
@@ -563,7 +577,8 @@ class PythonFinder {
     //                                                           X
     const info = [
       '**********************************************************',
-      'If you have non-displayed characters set "UTF-8" encoding.',
+      'If you have non-displayed characters, please set "UTF-8"',
+      'encoding.',
       'You need to install the latest version of Python.',
       'Node-gyp should be able to find and use Python. If not,',
       'you can try one of the following options:',