Update javadoc to reflect recent LinkageCache changes

[abyrd]

This is a pure documentation change, fixing some obsolete information I noticed during a recent call.

The final block of documentation in the changeset was changed only for consistency with surrounding comments. It will take longer to work through the open questions in that block and verify current behavior. That would be useful, but I don't think I will reach reliable conclusions on that part by the time we do the release.

[ansoncfit]

I made one small suggestion for clarity.

In our recent discussion, I mentioned a vague memory of another comment that might need to be updated. Is the description here still correct?

r5/src/main/java/com/conveyal/r5/analyst/cluster/AnalysisWorker.java

Lines 460 to 465 in e5a9a26

	// Pull all necessary inputs into cache in a blocking fashion, unlike single-point tasks where prep is async.
	// Avoids auto-shutdown while preloading. Must be done after loading destination pointsets to establish extents.
	// Note we're completely bypassing the async loader here and relying on the older nested LoadingCaches.
	// If those are ever removed, the async loader will need a synchronous mode with per-path blocking (kind of
	// reinventing the wheel of LoadingCache) or we'll need to make preparation for regional tasks async.
	TransportNetwork transportNetwork = networkPreloader.synchronousPreload(task);

[abyrd]

Is the description here still correct?

I think it is still correct, though the way it's phrased might be confusing. When it says "completely bypassing the async loader" it means that while we're still using the async loader class, we're using a method on that class that intentionally skips all the async or background proccessing machinery.

When a regional analysis starts up, we have N tasks all trying to preload at once, and they all block on this method. We don't want N threads performing the slow or heavy calculation steps of preloading redundantly. Nothing in the async loader class itself is causing them to take turns or wait for one preload to finish and share with the other threads. But behind the preloader class there are other caches that do enforce turn-taking and prevent redundant work.

[ansoncfit]

👍