docs: Improve clarity and conciseness of comments and documentation

lib/core/sudo.sh

@@ -16,6 +16,7 @@ check_touchid_support() {
     return 1
 }
 
+# Detect clamshell mode (lid closed)
 is_clamshell_mode() {
     # ioreg is missing (not macOS) -> treat as lid open
     if ! command -v ioreg > /dev/null 2>&1; then
@@ -182,8 +183,7 @@ request_sudo_access() {
 MOLE_SUDO_KEEPALIVE_PID=""
 MOLE_SUDO_ESTABLISHED="false"
 
-# Start sudo keepalive background process
-# Returns: PID of keepalive process
+# Start sudo keepalive
 _start_sudo_keepalive() {
     # Start background keepalive process with all outputs redirected
     # This is critical: command substitution waits for all file descriptors to close
@@ -212,8 +212,7 @@ _start_sudo_keepalive() {
     echo $pid
 }
 
-# Stop sudo keepalive process
-# Args: $1 - PID of keepalive process
+# Stop sudo keepalive
 _stop_sudo_keepalive() {
     local pid="${1:-}"
     if [[ -n "$pid" ]]; then
@@ -227,8 +226,7 @@ has_sudo_session() {
     sudo -n true 2> /dev/null
 }
 
-# Request sudo access (wrapper for common.sh function)
-# Args: $1 - prompt message
+# Request administrative access
 request_sudo() {
     local prompt_msg="${1:-Admin access required}"
 
@@ -244,8 +242,7 @@ request_sudo() {
     fi
 }
 
-# Ensure sudo session is established with keepalive
-# Args: $1 - prompt message
+# Maintain active sudo session with keepalive
 ensure_sudo_session() {
     local prompt="${1:-Admin access required}"
 
@@ -287,8 +284,7 @@ register_sudo_cleanup() {
     trap stop_sudo_session EXIT INT TERM
 }
 
-# Check if sudo is likely needed for given operations
-# Args: $@ - list of operations to check
+# Predict if operation requires administrative access
 will_need_sudo() {
     local -a operations=("$@")
     for op in "${operations[@]}"; do