Add explanatory comments

Add explanatory comments and documentation for complex logic, non-obvious code behavior, method parameters, and API functionality to improve code readability and maintainability.

This applies to several scenarios:

• Complex algorithms or logic that aren’t immediately clear from the code
• Boolean parameters or magic values that need explanation
• Method behavior that has side effects or special conditions
• Constructor parameters and their roles
• API methods missing complete documentation

Examples:

// Comment explaining complex logic
if (entry.getKey() == null) {
  // Remove entry when key is null - using value as the key to remove
  normalizedEntries.remove(entry.getValue());
}

// Comment explaining boolean parameter meaning
SpawnInputExpander spawnInputExpander = new SpawnInputExpander(execRoot, /* relativeToExecRoot= */ false);

// Complete method documentation
/**
 * Renames the file or directory from src to dst.
 * Parent directories are created as needed. If the target already exists, it will be overwritten.
 * 
 * @param clientEnv the client environment variables used for subprocess execution
 */

The goal is to make code self-documenting through clear comments that explain the “why” behind non-obvious implementation decisions, parameter meanings, and expected behavior.