Trim comments and docstrings

esphome/espidf/size_summary.py

@@ -35,8 +35,6 @@ _SIZE_SUFFIXES = {"K": 1024, "M": 1024 * 1024}
 def _parse_size(token: str) -> int:
     token = token.strip()
     if not token:
-        # A blank size cell is a malformed row; naming it beats a
-        # meaningless "from 0 bytes" bar downstream
         raise ValueError("blank partition size cell")
     if token.startswith(("0x", "0X")):
         return int(token, 16)
@@ -82,16 +80,11 @@ def _format_bar(used: int, total: int) -> str:
 
 
 def print_summary(size_json: Path, partitions_csv: Path | None) -> None:
-    """Print PlatformIO-shaped RAM and Flash one-liners.
-
-    Failures are non-fatal: the build has already succeeded, we just couldn't
-    summarize. Logs the cause at debug level.
-    """
+    """Print PlatformIO-shaped RAM and Flash one-liners; never fails the build."""
     try:
         _print_summary(size_json, partitions_csv)
     except Exception as e:  # noqa: BLE001  # pylint: disable=broad-exception-caught
-        # The named guards below cover the known shapes; this net keeps the
-        # promise for the rest (nested non-dict values, non-numeric sizes)
+        # Backstop for shapes the named guards below miss
         _LOGGER.debug("Skipping size summary: %s", e)
 
 
@@ -106,8 +99,7 @@ def _print_summary(size_json: Path, partitions_csv: Path | None) -> None:
         return
 
     if not isinstance(data, dict):
-        # Valid JSON that is not an object (a hand-edited or tool-emitted
-        # array) has no .get; skip with the file named
+        # Non-object JSON has no .get
         _LOGGER.debug("Skipping size summary: unexpected shape in %s", size_json)
         return
 
@@ -127,10 +119,7 @@ def _print_summary(size_json: Path, partitions_csv: Path | None) -> None:
         _LOGGER.debug("Skipping Flash summary: %s", e)
         return
     if app_size <= 0:
-        # Defensive backstop behind _parse_size's blank-cell rejection: a
-        # "from 0 bytes" denominator is meaningless to a reader. Note the
-        # skip costs CI's memory-impact extraction its Flash match, which
-        # is the loud outcome a broken partition table deserves.
+        # Skipping also fails CI's Flash extraction, the right outcome here
         _LOGGER.debug("Skipping Flash summary: app partition size is 0")
         return
     print(f"Flash: {_format_bar(image_size, app_size)}")

tests/unit_tests/test_size_summary.py

@@ -142,8 +142,7 @@ def test_print_summary_non_dict_json_is_skipped(
 def test_print_summary_unreadable_partitions_is_skipped(
     tmp_path: Path, capsys: pytest.CaptureFixture[str]
 ) -> None:
-    """An OSError reading the partition table skips the summary, never the
-    build (a missing file takes the ValueError path instead)."""
+    """An OSError reading the partition table skips the summary, not the build."""
     size_json = tmp_path / "size.json"
     size_json.write_text(
         '{"memory_types": {"DRAM": {"used": 1, "size": 2}}, "image_size": 100}'
@@ -166,8 +165,7 @@ def test_print_summary_unreadable_partitions_is_skipped(
 def test_print_summary_zero_app_partition_is_skipped(
     tmp_path: Path, capsys: pytest.CaptureFixture[str]
 ) -> None:
-    """A partition row parsing to size 0 must not render a 0% bar for CI's
-    memory-impact extraction to ingest."""
+    """A 0-size app partition drops the Flash bar instead of rendering 0%."""
     size_json = tmp_path / "size.json"
     size_json.write_text(
         '{"memory_types": {"DRAM": {"used": 1, "size": 2}}, "image_size": 100}'
@@ -205,8 +203,7 @@ def test_print_summary_happy_path_prints_both_bars(
 def test_print_summary_nested_bad_shapes_never_raise(
     tmp_path: Path, capsys: pytest.CaptureFixture[str], payload: dict
 ) -> None:
-    """The blanket guard keeps nested non-dict values and non-numeric sizes
-    from raising past a linked build."""
+    """The blanket guard keeps unexpected nested shapes from raising."""
     size_json = _write_size_json(tmp_path, payload)
     print_summary(size_json, None)
     assert "Traceback" not in capsys.readouterr().err
@@ -215,8 +212,7 @@ def test_print_summary_nested_bad_shapes_never_raise(
 def test_print_summary_blank_size_cell_names_the_row(
     tmp_path: Path, capsys: pytest.CaptureFixture[str]
 ) -> None:
-    """A blank size cell is reported as the malformed input it is, via the
-    ValueError path, instead of parsing to 0."""
+    """A blank size cell raises ValueError instead of parsing to 0."""
     size_json = _write_size_json(
         tmp_path,
         {"memory_types": {"DRAM": {"used": 1, "size": 2}}, "image_size": 100},