Add comments and lightly refactor to improve clarity

[holly-cummins]

See (painful) discussion on #47892 (comment). Having invested the brainpower in figuring out what's going on, I decided I should add some comments to help future developers (most likely future me), and rename a few things to maybe make things slightly clearer.

In general, the shutdownTasks.add(doTheAction) pattern confuses me every time I hit it, because I assume doTheAction is producing something which happens at shutdown. That's sort of true, but it misses the massive side effect of doTheAction happening now. So the doTheAction method name is referring to what's happening now, not what's happening at shutdown, even though it's wrapped in shutdownTasks.add. The names and structure all just end up being a bit misleading. I don't see an alternative to the pattern, though. I guess you could pass the shutdownTasks in to the method, and then it would be self-cleaning. That's no good for the case where we do cleanup in a finally block, though.

[quarkus-bot]

Status for workflow Quarkus CI

This is the status report for running Quarkus CI on commit 047a8ed.

Failing Jobs

Status	Name	Step	Failures	Logs	Raw logs	Build scan
✖	Native Tests - Spring		⚠️ Check →	Logs	Raw logs	🚧

---

Flaky tests - Develocity

⚙️ JVM Integration Tests - JDK 17

📦 integration-tests/opentelemetry

✖ io.quarkus.it.opentelemetry.LoggingResourceTest.testException - History

• Condition with Lambda expression in io.quarkus.it.opentelemetry.LoggingResourceTest was not fulfilled within 2 minutes. - org.awaitility.core.ConditionTimeoutException

org.awaitility.core.ConditionTimeoutException: Condition with Lambda expression in io.quarkus.it.opentelemetry.LoggingResourceTest was not fulfilled within 2 minutes.
	at org.awaitility.core.ConditionAwaiter.await(ConditionAwaiter.java:167)
	at org.awaitility.core.CallableCondition.await(CallableCondition.java:78)
	at org.awaitility.core.CallableCondition.await(CallableCondition.java:26)
	at org.awaitility.core.ConditionFactory.until(ConditionFactory.java:1160)
	at org.awaitility.core.ConditionFactory.until(ConditionFactory.java:1129)
	at io.quarkus.it.opentelemetry.LoggingResourceTest.testException(LoggingResourceTest.java:113)
	at java.base/java.lang.reflect.Method.invoke(Method.java:569)

---

⚙️ JVM Integration Tests - JDK 21

📦 integration-tests/opentelemetry

✖ io.quarkus.it.opentelemetry.LoggingResourceTest.testException - History

• Condition with Lambda expression in io.quarkus.it.opentelemetry.LoggingResourceTest was not fulfilled within 2 minutes. - org.awaitility.core.ConditionTimeoutException

org.awaitility.core.ConditionTimeoutException: Condition with Lambda expression in io.quarkus.it.opentelemetry.LoggingResourceTest was not fulfilled within 2 minutes.
	at org.awaitility.core.ConditionAwaiter.await(ConditionAwaiter.java:167)
	at org.awaitility.core.CallableCondition.await(CallableCondition.java:78)
	at org.awaitility.core.CallableCondition.await(CallableCondition.java:26)
	at org.awaitility.core.ConditionFactory.until(ConditionFactory.java:1160)
	at org.awaitility.core.ConditionFactory.until(ConditionFactory.java:1129)
	at io.quarkus.it.opentelemetry.LoggingResourceTest.testException(LoggingResourceTest.java:113)
	at java.base/java.lang.reflect.Method.invoke(Method.java:580)