archival: add a note about max_offset_override_exclusive

Outrageously verbose but for a good reason.

(cherry picked from commit 15ac281)

src/v/archival/ntp_archiver_service.cc

@@ -2036,9 +2036,9 @@ model::offset ntp_archiver::max_uploadable_offset_exclusive() const {
 }
 
 ss::future<ntp_archiver::batch_result> ntp_archiver::upload_next_candidates(
-  std::optional<model::offset> max_offset_override_exclusive) {
-    auto max_offset_exclusive = max_offset_override_exclusive
-                                  ? *max_offset_override_exclusive
+  std::optional<model::offset> unsafe_max_offset_override_exclusive) {
+    auto max_offset_exclusive = unsafe_max_offset_override_exclusive
+                                  ? *unsafe_max_offset_override_exclusive
                                   : max_uploadable_offset_exclusive();
     vlog(
       _rtclog.debug,

src/v/archival/ntp_archiver_service.h

@@ -187,12 +187,14 @@ class ntp_archiver {
     /// will pick not more than '_concurrency' candidates and start
     /// uploading them.
     ///
-    /// \param max_offset_override_exclusive Overrides the maximum offset
-    ///        that can be uploaded. If nullopt, the maximum offset is
-    ///        calculated automatically.
+    /// \param unsafe_max_offset_override_exclusive Overrides the maximum offset
+    ///        that can be uploaded. ONLY FOR TESTING. It is not clamped to a
+    ///        safe value/committed offset as some tests work directly with
+    ///        segments bypassing the raft thus not advancing the committed
+    ///        offset.
     /// \return future that returns number of uploaded/failed segments
     virtual ss::future<batch_result> upload_next_candidates(
-      std::optional<model::offset> max_offset_override_exclusive
+      std::optional<model::offset> unsafe_max_offset_override_exclusive
       = std::nullopt);
 
     ss::future<cloud_storage::download_result> sync_manifest();