From c10fb884302d649e5db683fb732c59b82616198a Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@home-assistant.io>
Date: Wed, 26 Aug 2026 09:34:37 -0500
Subject: [PATCH] Trim comments to repo standard

---
 esphome/build_gen/espidf.py  | 17 +++++++----------
 esphome/build_helpers/pch.py | 13 +++++--------
 esphome/espidf/toolchain.py  |  3 +--
 3 files changed, 13 insertions(+), 20 deletions(-)

diff --git a/esphome/build_gen/espidf.py b/esphome/build_gen/espidf.py
index 3a8e6ac6b0..e26b3a9408 100644
--- a/esphome/build_gen/espidf.py
+++ b/esphome/build_gen/espidf.py
@@ -292,17 +292,15 @@ target_link_options(${{COMPONENT_LIB}} PUBLIC
 def _pch_cmake() -> str:
     """The src component's precompiled-header block (C++ TUs only).
 
-    The -include stays relative (resolved from the compilers' cwd, the
-    build dir, where prepare_pch() puts the header and .gch); an absolute
-    path would poison ccache keys with the per-device build path.
+    The -include stays relative (resolved from the compiler cwd, the build
+    dir); an absolute path would poison ccache keys.
     """
     if not pch_enabled():
         return ""
     return f"""
-# ESPHome precompiled header (see esphome/build_helpers/pch.py). The
-# OBJECT_DEPENDS edge is on the header, not the .gch: headers baked into
-# a .gch drop out of the TU depfiles, and prepare_pch() touches the
-# header whenever it rebuilds the .gch so consumers recompile.
+# ESPHome precompiled header (see esphome/build_helpers/pch.py).
+# OBJECT_DEPENDS is on the header, not the .gch: pch-baked headers drop
+# out of TU depfiles, and prepare_pch() touches the header on rebuild.
 target_compile_options(${{COMPONENT_LIB}} PRIVATE
     "$<$<COMPILE_LANGUAGE:CXX>:-Winvalid-pch>"
     "$<$<COMPILE_LANGUAGE:CXX>:-include>"
@@ -329,9 +327,8 @@ def prepare_pch() -> None:
     try:
         sdkconfig = sdkconfig_path.read_text(encoding="utf-8")
     except OSError as err:
-        # Fail closed: the sdkconfig is the only config-awareness the .sum
-        # has for options that surface via sdkconfig.h, and any stand-in
-        # marker would collide across devices
+        # Fail closed: the sdkconfig is the .sum's only config identity for
+        # sdkconfig.h-only options; a stand-in marker would collide
         _LOGGER.warning(
             "Could not read %s; compiling without the pch: %s", sdkconfig_path, err
         )
diff --git a/esphome/build_helpers/pch.py b/esphome/build_helpers/pch.py
index 26545762d1..bf57a157e3 100644
--- a/esphome/build_helpers/pch.py
+++ b/esphome/build_helpers/pch.py
@@ -171,9 +171,8 @@ def pch_checksum(
     return digest.hexdigest()
 
 
-# Compile-command tokens dropped when retargeting a TU's flags at the
-# prefix header: source/output/depfile flags with an argument, and the
-# argument-less depfile flags (the pch compile must not touch depfiles)
+# Tokens dropped when retargeting a TU's flags at the prefix header
+# (the pch compile must not touch depfiles)
 _PCH_STRIP_FLAGS_WITH_ARG = frozenset({"-o", "-c", "-MT", "-MF", "-MQ"})
 _PCH_STRIP_FLAGS = frozenset({"-MD", "-MMD", "-MP", "-MM", "-M"})
 
@@ -225,8 +224,7 @@ def pch_compile_command(
     if tokens and is_launcher(tokens[0]):
         tokens = tokens[1:]
     if not tokens:
-        # An "arguments"-style or empty entry must skip cleanly, not spawn
-        # a compiler-less argv that warns on every build
+        # "arguments"-style or empty entries must skip, not spawn "-x ..."
         _LOGGER.warning("Compile database entry has no usable command, skipping pch")
         return None
     args: list[str] = []
@@ -302,9 +300,8 @@ def prepare_pch(
         discard_pch(build_dir)
         return
     cmd, cmd_dir = cmd_and_dir
-    # Stripped like ccache's own rewriting (a user CCACHE_BASEDIR wins) so
-    # identical configs hash identically across devices; the raw build path
-    # covers unresolved spellings in the compile DB
+    # Strip like ccache's rewriting (user CCACHE_BASEDIR wins); the raw
+    # build path covers unresolved (symlinked) spellings
     cmd_id = (
         " ".join(cmd)
         .replace(effective_ccache_basedir(), "")
diff --git a/esphome/espidf/toolchain.py b/esphome/espidf/toolchain.py
index 0eccf5af79..82f64defca 100644
--- a/esphome/espidf/toolchain.py
+++ b/esphome/espidf/toolchain.py
@@ -536,8 +536,7 @@ def run_compile(config, verbose: bool) -> int:
     try:
         prepare_pch()
     except Exception:  # noqa: BLE001  # pylint: disable=broad-exception-caught
-        # Discard so an unexpected error can never leave a stale .gch that
-        # GCC would silently consume; exc_info keeps the failure diagnosable
+        # Discard so a stale .gch can never be consumed
         with suppress(OSError):
             discard_pch()
         _LOGGER.warning(