diff --git a/esphome/helpers.py b/esphome/helpers.py
index bb1984e17c..9d341af146 100644
--- a/esphome/helpers.py
+++ b/esphome/helpers.py
@@ -465,6 +465,12 @@ def _write_file(
 
 
 def write_file(path: Path, text: str | bytes, private: bool = False) -> None:
+    """Atomically write text or bytes to path. Wraps OSError as EsphomeError.
+
+    Used by esphome-device-builder for in-place YAML rewrites; the
+    atomicity (sibling tempfile + shutil.move) and EsphomeError
+    wrapping are part of the public contract.
+    """
     try:
         _write_file(path, text, private=private)
     except OSError as err: