Add comments, change names for understanding

src/Control/SingleRun.hs

@@ -84,6 +84,12 @@ singleRun sr@(SingleRun var f) k =
 
                         -- OK, we're done running, so let other
                         -- threads run this again.
+
+                        -- NB: as soon as we've modified the MVar, the next
+                        -- call to singleRun will think no thread is working and
+                        -- start over. Anything waiting on us will get our
+                        -- result, but nobody else will. That's ok: singleRun
+                        -- just provides a little caching on top of a mutex.
                         modifyMVar_ var $ return . filter (\(k', _) -> k /= k')
 
                         case eres of

src/Stackage/Database/Cron.hs

@@ -414,12 +414,12 @@ checkForDocs snapshotId snapName = do
     -- Cache is for SnapshotPackageId, there will be many modules per peckage, no need to look into
     -- the database for each one of them.
     n <- max 1 . (`div` 2) <$> getNumCapabilities
-    notFoundList <- lift $ pooledMapConcurrentlyN n (markModules sidsCacheRef) mods
+    unexpectedPackages <- lift $ pooledMapConcurrentlyN n (markModules sidsCacheRef) mods
-    forM_ (Set.fromList $ catMaybes notFoundList) $ \pid ->
+    forM_ (Set.fromList $ catMaybes unexpectedPackages) $ \pid ->
         lift $
         logWarn $
-        "Documentation available for package '" <> display pid <>
+        "Documentation found for package '" <> display pid <>
-        "' but was not found in this snapshot: " <>
+        "', which does not exist in this snapshot: " <>
         display snapName
   where
     prefix = textDisplay snapName <> "/"
@@ -433,7 +433,7 @@ checkForDocs snapshotId snapName = do
         let mSnapshotPackageId = Map.lookup pid sidsCache
         mFound <- run $ markModuleHasDocs snapshotId pid mSnapshotPackageId modName
         case mFound of
-            Nothing -> pure $ Just pid
+            Nothing -> pure $ Just pid -- This package doesn't exist in the snapshot!
             Just snapshotPackageId
                 | Nothing <- mSnapshotPackageId -> do
                     atomicModifyIORef'

stack.yaml

@@ -1,5 +1,17 @@
 resolver: lts-22.6
 extra-deps:
+# WARNING: Changing the hoogle version causes stackage-server-cron to regenerate
+# Hoogle databases FOR EVERY SNAPSHOT, EVER. Usually, that's ok! But don't
+# forget! The consequences are: (1) More disk usage. Hoogle databases are not
+# cleaned up on the stackage-server-cron side, nor on the stackage-server side.
+# (Yet. This will change.) (2) More bucket usage. While it's easy to say it's a
+# drop in the literal bucket, such excessive misuse of storage makes
+# administration, backups, disaster recovery, and many other DevOps concerns
+# harder and harder. All but the latest LTS's database are literally never used
+# anyway. (3) The Hoogle database schema is defined by the first three
+# version components. Any more frequent regeneration is pure unadulterated
+# waste. (4) Stackage's Hoogle search will be unavailable until the new
+# databases have been generated.
 - hoogle-5.0.18.4@sha256:1372458e97dff541fcda099236af7936bf93ee6b8c5d15695ee6d9426dff5eed,3171
 - safe-0.3.20@sha256:7813ad56161f57d5162a924de5597d454162a2faed06be6e268b37bb5c19d48d,2312
 - Cabal-3.8.1.0@sha256:77121d8e1aff14a0fd95684b751599db78a7dd26d55862d9fcef27c88b193e9d,12609