updating comments about how this works

Author: heckj

common/README

@@ -11,21 +11,16 @@ Both files are intentionally minimal:
 - `header.html` uses DocC's `custom-header` template hook to add a Swift logo
   linking to swift.org to the masthead, between the sidebar-toggle control
   and the page title. It targets the masthead rather than the Navigator
-  sidebar itself because the masthead mounts once from data already known at
-  page load and never gets torn down and rebuilt — unlike the sidebar, which
-  swift-docc-render swaps from a loading-skeleton state to the real,
-  populated one once the navigator index data has loaded, discarding
-  whatever a script had inserted into the skeleton. The logo is appended as
-  the last child of `.pre-title` (the toggle's own wrapper) rather than
-  inserted as a sibling before `.nav-title`, because swift-docc-render's CSS
-  assigns the title its grid placement via the adjacent-sibling selector
-  `.pre-title + .nav-title`, which requires them to stay immediate siblings.
-  Because it's part of the persistent masthead rather than the sidebar, the
-  logo stays visible regardless of whether the sidebar is shown, hidden, or
-  a mobile drawer, with no extra positioning or z-index logic needed. It
-  also still reserves the `#version-switcher` div for a future
-  documentation-version switcher — add the switcher UI there when that
-  lands.
+  sidebar because the sidebar gets torn down and rebuilt once its data
+  loads (discarding anything inserted into its loading-skeleton state),
+  while the masthead mounts once and stays. The logo is appended inside
+  `.pre-title` rather than inserted as a sibling before `.nav-title`, since
+  swift-docc-render positions the title via the adjacent-sibling CSS rule
+  `.pre-title + .nav-title`, which needs them to stay adjacent. Being part
+  of the masthead rather than the sidebar, it stays visible regardless of
+  the sidebar's shown/hidden/drawer state. It also still reserves the
+  `#version-switcher` div for a future documentation-version switcher — add
+  the switcher UI there when that lands.
 - `footer.html` carries the copyright/trademark notice, the same legal links
   (License, Security, Privacy Policy, Cookies) swift.org's footer has, and
   an Adobe Analytics page-activation snippet mirroring swift.org's

common/header.html

@@ -12,31 +12,18 @@
 
 <script>
 (function () {
-  // Sourced from swiftlang/swift-org-website's assets/images/icon-swift.svg
-  // (the currentColor variant, meant for light/dark masthead use — the
-  // upstream asset intentionally leaves fill unset so consumers apply their
-  // own; fill="currentColor" below is added here to do that).
+  // Sourced from swiftlang/swift-org-website's assets/images/icon-swift.svg,
+  // the currentColor variant — fill="currentColor" below is added here since
+  // the upstream asset leaves it unset for consumers to apply.
   var LOGO_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="22" height="22" aria-hidden="true"><path fill="currentColor" fill-rule="nonzero" transform="matrix(.351937 0 0 .351937 -1.96558 -2.00601)" d="m46.955 36.578c-.002-.002-.003-.003-.005-.005.066-.223.134-.445.191-.673 2.46-9.799-3.543-21.384-13.701-27.484 4.452 6.035 6.42 13.344 4.671 19.735-.156.571-.343 1.118-.55 1.65-.225-.148-.509-.316-.889-.526 0 0-10.104-6.238-21.055-17.273-.288-.29 5.839 8.757 12.793 16.104-3.276-1.839-12.406-8.482-18.186-13.772.71 1.185 1.555 2.325 2.483 3.423 4.827 6.121 11.121 13.673 18.662 19.473-5.298 3.242-12.785 3.494-20.239.003-1.844-.864-3.577-1.907-5.182-3.091 3.156 5.047 8.015 9.401 13.93 11.943 7.054 3.032 14.068 2.826 19.292.05l-.004.006c.024-.015.054-.031.079-.047.214-.115.427-.232.636-.356 2.51-1.303 7.467-2.625 10.129 2.553.651 1.267 2.036-5.448-3.055-11.713z"/></svg>';
 
-  // The masthead (.nav-content > .pre-title, .nav-title, .nav-menu) is
-  // rendered client-side by swift-docc-render (Vue), not present in this
-  // page's initial HTML, so it may not exist yet when this script runs —
-  // retry via MutationObserver until it mounts. Unlike the Navigator
-  // sidebar, the masthead has no loading-skeleton/real-content swap to
-  // race against: it mounts once from data already known at page load and
-  // stays, so this observer keeps running (harmlessly, guarded by the
-  // .masthead-swift-logo check below) rather than needing to disconnect at
-  // a precise moment.
-  //
-  // Appended as the last child of `.pre-title` rather than inserted as a
-  // sibling between `.pre-title` and `.nav-title`: swift-docc-render's own
-  // CSS assigns `.nav-title` its grid placement via the adjacent-sibling
-  // selector `.pre-title + .nav-title`, which requires them to stay
-  // immediate siblings. Landing inside `.pre-title` keeps that intact while
-  // still sitting visually between the sidebar toggle and the title text —
-  // and, being part of the persistent masthead rather than the sidebar
-  // itself, it stays visible regardless of whether the sidebar is shown,
-  // hidden, or a mobile drawer.
+  // Appended inside `.pre-title` rather than inserted as a sibling before
+  // `.nav-title`: swift-docc-render positions the title via the CSS rule
+  // `.pre-title + .nav-title`, which needs them to stay adjacent siblings.
+  // This keeps that intact while still landing between the sidebar toggle
+  // and the title — and, being part of the masthead rather than the
+  // sidebar, it stays visible regardless of the sidebar's own
+  // shown/hidden/drawer state.
   function insertLogoLink() {
     var preTitle = document.querySelector('.pre-title');
     if (!preTitle || preTitle.querySelector('.masthead-swift-logo')) {