diff --git a/lib/Epub/Epub/ParsedText.cpp b/lib/Epub/Epub/ParsedText.cpp
index 67975c3..3320da0 100644
--- a/lib/Epub/Epub/ParsedText.cpp
+++ b/lib/Epub/Epub/ParsedText.cpp
@@ -25,6 +25,7 @@ void ParsedText::layoutAndExtractLines(const GfxRenderer& renderer, const int fo
     return;
   }
 
+  // horizontalMargin accounts for both left and right gutters, leaving the drawable width.
   const int pageWidth = renderer.getScreenWidth() - horizontalMargin;
   if (pageWidth <= 0) {
     words.clear();
@@ -50,6 +51,7 @@ void ParsedText::layoutAndExtractLines(const GfxRenderer& renderer, const int fo
   std::vector<uint16_t> lineWordWidths;
   lineWordWidths.reserve(16);
 
+  // Guard against malicious/invalid content generating unbounded line counts.
   size_t producedLines = 0;
   constexpr size_t MAX_LINES = 1000;
 
@@ -186,6 +188,7 @@ void ParsedText::layoutAndExtractLines(const GfxRenderer& renderer, const int fo
       continue;
     }
 
+    // No more tricks available; flush the collected words and move on.
     commitLine(false);
   }
 
diff --git a/lib/Epub/Epub/hyphenation/Hyphenator.cpp b/lib/Epub/Epub/hyphenation/Hyphenator.cpp
index 5040946..fff1a61 100644
--- a/lib/Epub/Epub/hyphenation/Hyphenator.cpp
+++ b/lib/Epub/Epub/hyphenation/Hyphenator.cpp
@@ -110,16 +110,19 @@ bool Hyphenator::splitWord(const GfxRenderer& renderer, const int fontId, const
     return false;
   }
 
+  // Skip mixed tokens (e.g., "v2.0") unless the caller forces a split due to overflow.
   if (!force && !hasOnlyAlphabetic(cps)) {
     return false;
   }
 
   const auto breakIndexes = collectBreakIndexes(cps);
+  // Budget for a trailing hyphen so rendered width matches the layout test.
   const int hyphenWidth = renderer.getTextWidth(fontId, "-", style);
   const int adjustedWidth = availableWidth - hyphenWidth;
 
   size_t chosenIndex = std::numeric_limits<size_t>::max();
 
+  // Prefer dictionary-style break points emitted by language hyphenators.
   if (adjustedWidth > 0) {
     for (const size_t idx : breakIndexes) {
       const size_t byteOffset = byteOffsetForIndex(cps, idx);
@@ -160,6 +163,7 @@ bool Hyphenator::splitWord(const GfxRenderer& renderer, const int fontId, const
     return false;
   }
 
+  // Append the printed hyphen to the prefix while leaving the tail untouched.
   result->head = head + "-";
   result->tail = tail;
   return true;