update comments

Author: Jason2866

builder/frameworks/arduino.py

@@ -886,7 +886,7 @@ def get_frameworks_in_current_env():
 if flag_custom_sdkconfig and not flag_any_custom_sdkconfig:
     call_compile_libs()
 
-# Main logic for Arduino Framework
+# Arduino framework configuration and build logic
 pioframework = env.subst("$PIOFRAMEWORK")
 arduino_lib_compile_flag = env.subst("$ARDUINO_LIB_COMPILE_FLAG")
 

builder/frameworks/component_manager.py

@@ -252,7 +252,7 @@ def _get_or_create_component_yml(self) -> str:
         Returns:
             Absolute path to the component YAML file
         """
-        # Try Arduino framework first
+        # Check Arduino framework directory first
         afd = self.config.arduino_framework_dir
         framework_yml = str(Path(afd) / "idf_component.yml") if afd else ""
         if framework_yml and os.path.exists(framework_yml):

builder/frameworks/espidf.py

@@ -1672,8 +1672,8 @@ def get_python_exe():
 
 ensure_python_venv_available()
 
-# ESP-IDF package doesn't contain .git folder, instead package version is specified
-# in a special file "version.h" in the root folder of the package
+# ESP-IDF package version is determined from version.h file
+# since the package distribution doesn't include .git metadata
 
 create_version_file()
 
@@ -1712,7 +1712,7 @@ def get_python_exe():
 
 
 #
-# Current build script limitations
+# Known build system limitations
 #
 
 if any(" " in p for p in (FRAMEWORK_DIR, BUILD_DIR)):
@@ -1751,12 +1751,12 @@ def get_python_exe():
         LIBSOURCE_DIRS=[str(Path(ARDUINO_FRAMEWORK_DIR) / "libraries")]
     )
 
-# Set ESP-IDF version environment variables (needed for proper Kconfig processing)
+# Configure ESP-IDF version environment variables for Kconfig processing
 framework_version = get_framework_version()
 major_version = framework_version.split('.')[0] + '.' + framework_version.split('.')[1]
 os.environ["ESP_IDF_VERSION"] = major_version
 
-# Configure CMake arguments with ESP-IDF version
+# Setup CMake configuration arguments
 extra_cmake_args = [
     "-DIDF_TARGET=" + idf_variant,
     "-DPYTHON_DEPS_CHECKED=1",
@@ -1850,7 +1850,7 @@ def get_python_exe():
     env.Depends("$BUILD_DIR/$PROGNAME$PROGSUFFIX", build_bootloader(sdk_config))
 
 #
-# Target: ESP-IDF menuconfig
+# ESP-IDF menuconfig target implementation
 #
 
 env.AddPlatformTarget(
@@ -1995,8 +1995,8 @@ def _skip_prj_source_files(node):
 ):
     project_env = env.Clone()
     if project_target_name != "__idf_main":
-        # Manually add dependencies to CPPPATH since ESP-IDF build system doesn't generate
-        # this info if the folder with sources is not named 'main'
+        # Add dependencies to CPPPATH for non-main source directories
+        # ESP-IDF build system requires manual dependency handling for custom source folders
         # https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html#rename-main
         project_env.AppendUnique(CPPPATH=app_includes["plain_includes"])
 
@@ -2044,7 +2044,7 @@ def _skip_prj_source_files(node):
 #
 
 extra_elf2bin_flags = "--elf-sha256-offset 0xb0"
-# https://github.com/espressif/esp-idf/blob/master/components/esptool_py/project_include.cmake#L58
+# Reference: ESP-IDF esptool_py component configuration
 # For chips that support configurable MMU page size feature
 # If page size is configured to values other than the default "64KB" in menuconfig,
 mmu_page_size = "64KB"

builder/main.py

@@ -35,7 +35,7 @@
 from platformio.util import get_serial_ports
 from platformio.compat import IS_WINDOWS
 
-# Initialize environment and configuration
+# Initialize SCons environment and project configuration
 env = DefaultEnvironment()
 platform = env.PioPlatform()
 projectconfig = env.GetProjectConfig()
@@ -45,10 +45,10 @@
 core_dir = projectconfig.get("platformio", "core_dir")
 build_dir = Path(projectconfig.get("platformio", "build_dir"))
 
-# Setup Python virtual environment and get executable paths
+# Configure Python environment through centralized platform management
 PYTHON_EXE, esptool_binary_path = platform.setup_python_env(env)
 
-# Initialize board configuration and MCU settings
+# Load board configuration and determine MCU architecture
 board = env.BoardConfig()
 board_id = env.subst("$BOARD")
 mcu = board.get("build.mcu", "esp32")
@@ -450,7 +450,7 @@ def switch_off_ldf():
 if not is_xtensa:
     toolchain_arch = "riscv32-esp"
 
-# Initialize integration extra data if not present
+# Ensure integration extra data structure exists
 if "INTEGRATION_EXTRA_DATA" not in env:
     env["INTEGRATION_EXTRA_DATA"] = {}
 
@@ -460,7 +460,7 @@ def switch_off_ldf():
     if ' ' in esptool_binary_path 
     else esptool_binary_path
 )
-# Configure build tools and environment variables
+# Configure SCons build tools and compiler settings
 env.Replace(
     __get_board_boot_mode=_get_board_boot_mode,
     __get_board_f_flash=_get_board_f_flash,
@@ -636,7 +636,7 @@ def firmware_metrics(target, source, env):
         if env.GetProjectOption("custom_esp_idf_size_verbose", False):
             print(f"Running command: {' '.join(cmd)}")
 
-        # Call esp-idf-size with modified environment
+        # Execute esp-idf-size with current environment
         result = subprocess.run(cmd, check=False, capture_output=False, env=os.environ)
 
         if result.returncode != 0:

builder/penv_setup.py

@@ -41,7 +41,7 @@
     re.IGNORECASE,
 )
 
-# Python dependencies required for the build process
+# Python dependencies required for ESP32 platform builds
 python_deps = {
     "platformio": "https://github.com/pioarduino/platformio-core/archive/refs/tags/v6.1.18.zip",
     "pyyaml": ">=6.0.2",
@@ -89,7 +89,7 @@ def setup_pipenv_in_package(env, penv_dir):
         str or None: Path to uv executable if uv was used, None if python -m venv was used
     """
     if not os.path.exists(penv_dir):
-        # First try to create virtual environment with uv
+        # Attempt virtual environment creation using uv package manager
         uv_success = False
         uv_cmd = None
         try:
@@ -125,8 +125,8 @@ def setup_pipenv_in_package(env, penv_dir):
                 )
             )
 
-        # Verify that the virtual environment was created properly
-        # Check for python executable
+        # Validate virtual environment creation
+        # Ensure Python executable is available
         assert os.path.isfile(
             get_executable_path(penv_dir, "python")
         ), f"Error: Failed to create a proper virtual environment. Missing the `python` binary! Created with uv: {uv_success}"
@@ -432,7 +432,7 @@ def _setup_python_environment_core(env, platform, platformio_dir, should_install
     """
     penv_dir = str(Path(platformio_dir) / "penv")
 
-    # Setup virtual environment if needed
+    # Create virtual environment if not present
     if env is not None:
         # SCons version
         used_uv_executable = setup_pipenv_in_package(env, penv_dir)
@@ -457,21 +457,21 @@ def _setup_python_environment_core(env, platform, platformio_dir, should_install
     esptool_binary_path = get_executable_path(penv_dir, "esptool")
     uv_executable = get_executable_path(penv_dir, "uv")
 
-    # Install espressif32 Python dependencies
+    # Install required Python dependencies for ESP32 platform
     if has_internet_connection() or github_actions:
         if not install_python_deps(penv_python, used_uv_executable):
             sys.stderr.write("Error: Failed to install Python dependencies into penv\n")
             sys.exit(1)
     else:
         print("Warning: No internet connection detected, Python dependency check will be skipped.")
 
-    # Install esptool after dependencies (if requested)
+    # Install esptool package if required
     if should_install_esptool:
         if env is not None:
             # SCons version
             install_esptool(env, platform, penv_python, uv_executable)
         else:
-            # Minimal version - install esptool from tl-install provided path
+            # Minimal setup - install esptool from tool package
             _install_esptool_from_tl_install(platform, penv_python, uv_executable)
 
     # Setup certifi environment variables
@@ -491,7 +491,7 @@ def _setup_pipenv_minimal(penv_dir):
         str or None: Path to uv executable if uv was used, None if python -m venv was used
     """
     if not os.path.exists(penv_dir):
-        # First try to create virtual environment with uv
+        # Attempt virtual environment creation using uv package manager
         uv_success = False
         uv_cmd = None
         try:
@@ -528,8 +528,8 @@ def _setup_pipenv_minimal(penv_dir):
                 sys.stderr.write(f"Error: Failed to create virtual environment: {e}\n")
                 sys.exit(1)
 
-        # Verify that the virtual environment was created properly
-        # Check for python executable
+        # Validate virtual environment creation
+        # Ensure Python executable is available
         assert os.path.isfile(
             get_executable_path(penv_dir, "python")
         ), f"Error: Failed to create a proper virtual environment. Missing the `python` binary! Created with uv: {uv_success}"

platform.py

@@ -45,7 +45,7 @@
 from platformio.package.manager.tool import ToolPackageManager
 
 
-# Import penv_setup functionality using explicit module loading
+# Import penv_setup functionality using explicit module loading for centralized Python environment management
 penv_setup_path = Path(__file__).parent / "builder" / "penv_setup.py"
 spec = importlib.util.spec_from_file_location("penv_setup", str(penv_setup_path))
 penv_setup_module = importlib.util.module_from_spec(spec)
@@ -226,7 +226,7 @@ def _check_tl_install_version(self) -> bool:
             logger.debug(f"No version check required for {tl_install_name}")
             return True
 
-        # Check if tool is already installed
+        # Check current installation status
         tl_install_path = self.packages_dir / tl_install_name
         package_json_path = tl_install_path / "package.json"
 
@@ -244,10 +244,10 @@ def _check_tl_install_version(self) -> bool:
                 logger.warning(f"Installed version for {tl_install_name} unknown, installing {required_version}")
                 return self._install_tl_install(required_version)
 
-            # IMPORTANT: Compare versions correctly
+            # Compare versions to avoid unnecessary reinstallation
             if self._compare_tl_install_versions(installed_version, required_version):
                 logger.debug(f"{tl_install_name} version {installed_version} is already correctly installed")
-                # IMPORTANT: Set package as available, but do NOT reinstall
+                # Mark package as available without reinstalling
                 self.packages[tl_install_name]["optional"] = True
                 return True
             else:
@@ -305,8 +305,7 @@ def _extract_version_from_url(self, version_string: str) -> str:
 
     def _install_tl_install(self, version: str) -> bool:
         """
-        Install tool-esp_install ONLY when necessary
-        and handles backwards compatibility for tl-install.
+        Install tool-esp_install with version validation and legacy compatibility.
 
         Args:
             version: Version string or URL to install
@@ -320,7 +319,7 @@ def _install_tl_install(self, version: str) -> bool:
         try:
             old_tl_install_exists = old_tl_install_path.exists()
             if old_tl_install_exists:
-                # remove outdated tl-install
+                # Remove legacy tl-install directory
                 safe_remove_directory(old_tl_install_path)
 
             if tl_install_path.exists():
@@ -331,17 +330,17 @@ def _install_tl_install(self, version: str) -> bool:
             self.packages[tl_install_name]["optional"] = False
             self.packages[tl_install_name]["version"] = version
             pm.install(version)
-            # Ensure backward compatibility by removing pio install status indicator
+            # Remove PlatformIO install marker to prevent version conflicts
             tl_piopm_path = tl_install_path / ".piopm"
             safe_remove_file(tl_piopm_path)
 
             if (tl_install_path / "package.json").exists():
                 logger.info(f"{tl_install_name} successfully installed and verified")
                 self.packages[tl_install_name]["optional"] = True
 
-                # Handle old tl-install to keep backwards compatibility
+                # Maintain backwards compatibility with legacy tl-install references
                 if old_tl_install_exists:
-                    # Copy tool-esp_install content to tl-install location
+                    # Copy tool-esp_install content to legacy tl-install location
                     if safe_copy_directory(tl_install_path, old_tl_install_path):
                         logger.info(f"Content copied from {tl_install_name} to old tl-install location")
                     else:
@@ -450,7 +449,7 @@ def _run_idf_tools_install(self, tools_json_path: str, idf_tools_path: str, penv
 
     def _check_tool_version(self, tool_name: str) -> bool:
         """Check if the installed tool version matches the required version."""
-        # Clean up versioned directories FIRST, before any version checks
+        # Clean up versioned directories before version checks to prevent conflicts
         self._cleanup_versioned_tool_directories(tool_name)
 
         paths = self._get_tool_paths(tool_name)
@@ -489,14 +488,14 @@ def install_tool(self, tool_name: str) -> bool:
         paths = self._get_tool_paths(tool_name)
         status = self._check_tool_status(tool_name)
 
-        # Get penv python if available
+        # Use centrally configured Python executable if available
         penv_python = getattr(self, '_penv_python', None)
 
-        # Case 1: New installation with idf_tools
+        # Case 1: Fresh installation using idf_tools.py
         if status['has_idf_tools'] and status['has_tools_json']:
             return self._install_with_idf_tools(tool_name, paths, penv_python)
 
-        # Case 2: Tool already installed, version check
+        # Case 2: Tool already installed, perform version validation
         if (status['has_idf_tools'] and status['has_piopm'] and
                 not status['has_tools_json']):
             return self._handle_existing_tool(tool_name, paths)
@@ -511,7 +510,7 @@ def _install_with_idf_tools(self, tool_name: str, paths: Dict[str, str], penv_py
         ):
             return False
 
-        # Copy tool files
+        # Copy tool metadata to IDF tools directory
         target_package_path = Path(IDF_TOOLS_PATH) / "tools" / tool_name / "package.json"
 
         if not safe_copy_file(paths['package_path'], target_package_path):
@@ -534,7 +533,7 @@ def _handle_existing_tool(self, tool_name: str, paths: Dict[str, str]) -> bool:
             logger.debug(f"Tool {tool_name} found with correct version")
             return True
 
-        # Wrong version, reinstall - cleanup is already done in _check_tool_version
+        # Version mismatch detected, reinstall tool (cleanup already performed)
         logger.info(f"Reinstalling {tool_name} due to version mismatch")
 
         # Remove the main tool directory (if it still exists after cleanup)
@@ -623,7 +622,7 @@ def _configure_installer(self) -> None:
             logger.error("Error during tool-esp_install version check / installation")
             return
 
-        # Remove pio install marker to avoid issues when switching versions
+        # Remove legacy PlatformIO install marker to prevent version conflicts
         old_tl_piopm_path = Path(self.packages_dir) / "tl-install" / ".piopm"
         if old_tl_piopm_path.exists():
             safe_remove_file(old_tl_piopm_path)
@@ -735,17 +734,17 @@ def _configure_filesystem_tools(self, variables: Dict, targets: List[str]) -> No
             self._install_filesystem_tool(filesystem, for_download=True)
 
     def setup_python_env(self, env):
-        """Setup Python virtual environment and return executable paths."""
-        # Penv should already be set up in configure_default_packages
+        """Configure SCons environment with centrally managed Python executable paths."""
+        # Python environment is centrally managed in configure_default_packages
         if hasattr(self, '_penv_python') and hasattr(self, '_esptool_path'):
-            # Update SCons environment with penv python
+            # Update SCons environment with centrally configured Python executable
             env.Replace(PYTHONEXE=self._penv_python)
             return self._penv_python, self._esptool_path
 
         # This should not happen, but provide fallback
         logger.warning("Penv not set up in configure_default_packages, setting up now")
 
-        # Use centralized minimal setup as a fallback and propagate into SCons
+        # Fallback to minimal setup if centralized configuration failed
         config = ProjectConfig.get_instance()
         core_dir = config.get("platformio", "core_dir")
         penv_python, esptool_path = setup_penv_minimal(self, core_dir, install_esptool=True)
@@ -769,7 +768,7 @@ def configure_default_packages(self, variables: Dict, targets: List[str]) -> Any
             self._configure_installer()
             self._install_esptool_package()
 
-            # THEN: Setup Python virtual environment completely
+            # Complete Python virtual environment setup
             config = ProjectConfig.get_instance()
             core_dir = config.get("platformio", "core_dir")