From a9f31dd95ca2bf369c55baefe70c7913db9bdb3a Mon Sep 17 00:00:00 2001
From: WindSoilder <WindSoilder@outlook.com>
Date: Mon, 1 Aug 2022 19:04:56 +0800
Subject: [PATCH] add comment

---
 crates/nu-command/src/system/run_external.rs | 4 ++--
 crates/nu-system/src/foreground.rs           | 9 ++++++++-
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/crates/nu-command/src/system/run_external.rs b/crates/nu-command/src/system/run_external.rs
index f8327a3f75..ceb53baed0 100644
--- a/crates/nu-command/src/system/run_external.rs
+++ b/crates/nu-command/src/system/run_external.rs
@@ -13,7 +13,7 @@ use nu_protocol::{Category, Example, ListStream, PipelineData, RawStream, Span,
 use itertools::Itertools;
 
 use nu_engine::CallExt;
-use nu_system::external_process_setup::{reset_foreground_id, set_foreground, setup_fg_external};
+use nu_system::external_process_setup::{reset_foreground_id, set_foreground, prepare_to_foreground};
 use pathdiff::diff_paths;
 use regex::Regex;
 
@@ -141,7 +141,7 @@ impl ExternalCommand {
 
         #[cfg(not(windows))]
         {
-            setup_fg_external(&mut process);
+            prepare_to_foreground(&mut process);
             child = process.spawn()
         }
 
diff --git a/crates/nu-system/src/foreground.rs b/crates/nu-system/src/foreground.rs
index 88a50b1ac7..00c3ecab24 100644
--- a/crates/nu-system/src/foreground.rs
+++ b/crates/nu-system/src/foreground.rs
@@ -5,7 +5,7 @@
 #[cfg(target_family = "unix")]
 pub mod external_process_setup {
     use std::os::unix::prelude::CommandExt;
-    pub fn setup_fg_external(external_command: &mut std::process::Command) {
+    pub fn prepare_to_foreground(external_command: &mut std::process::Command) {
         unsafe {
             libc::signal(libc::SIGTTOU, libc::SIG_IGN);
             libc::signal(libc::SIGTTIN, libc::SIG_IGN);
@@ -14,18 +14,24 @@ pub mod external_process_setup {
                 // make the command startup with new process group.
                 // The process group id must be the same as external commands' pid.
                 // Or else we'll failed to set it as foreground process.
+                // For more information, refer to `fork_child_for_process` function:
+                // https://github.com/fish-shell/fish-shell/blob/023042098396aa450d2c4ea1eb9341312de23126/src/exec.cpp#L398
                 libc::setpgid(0, 0);
                 Ok(())
             });
         }
     }
 
+    /// Before call this function, `prepare_to_foreground` function must be called.  Or else
+    /// it'll failed with silence.
     pub fn set_foreground(process: &std::process::Child) {
         unsafe {
             libc::tcsetpgrp(libc::STDIN_FILENO, process.id() as i32);
         }
     }
 
+    /// It can only be called when you have called `set_foreground`, or else
+    /// Something strange will happened.
     pub fn reset_foreground_id() {
         unsafe {
             libc::tcsetpgrp(libc::STDIN_FILENO, libc::getpgrp());
@@ -35,6 +41,7 @@ pub mod external_process_setup {
     }
 }
 
+// TODO: investigate if we can set foreground process through windows system call.
 #[cfg(target_family = "windows")]
 mod external_process_setup {