Add top-level comments

2 files changed, 21 insertions, 3 deletions

diff --git a/storage/src/vespa/storage/distributor/pendingmessagetracker.h b/storage/src/vespa/storage/distributor/pendingmessagetracker.h
index 5756c1ef8ab..39ea5c9c1a6 100644
--- a/storage/src/vespa/storage/distributor/pendingmessagetracker.h
+++ b/storage/src/vespa/storage/distributor/pendingmessagetracker.h
@@ -22,12 +22,21 @@
 
 namespace storage::distributor {
 
+/**
+ * Since the state a deferred task depends on may have changed between the
+ * time a task was scheduled and when it's actually executed, this enum provides
+ * a means of communicating if a task should be started as normal.
+ */
 enum class TaskRunState {
-    OK,
-    Aborted,
-    BucketLost
+    OK,        // Task may be started as normal
+    Aborted,   // Task should trigger an immediate abort behavior (distributor is shutting down)
+    BucketLost // Task should trigger an immediate abort behavior (bucket no longer present on node)
 };
 
+/**
+ * Represents an arbitrary task whose execution may be deferred until no
+ * further pending operations are present.
+ */
 struct DeferredTask {
     virtual ~DeferredTask() = default;
     virtual void run(TaskRunState state) = 0;
diff --git a/storage/src/vespa/storage/visiting/reindexing_visitor.h b/storage/src/vespa/storage/visiting/reindexing_visitor.h
index 1d2e9504ec9..9be21f24f5f 100644
--- a/storage/src/vespa/storage/visiting/reindexing_visitor.h
+++ b/storage/src/vespa/storage/visiting/reindexing_visitor.h
@@ -5,6 +5,15 @@
 
 namespace storage {
 
+/**
+ * A visitor instance that is intended to be used for background reindexing.
+ * Only meant to be run alongside distributor-level bucket locking support
+ * that prevents concurrent writes to documents in the visited bucket.
+ *
+ * The bucket lock is explicitly bypassed by the Puts sent by the visitor
+ * by having all these be augmented with a special TaS string that is
+ * recognized by the distributor.
+ */
 class ReindexingVisitor : public Visitor {
 public:
     explicit ReindexingVisitor(StorageComponent& component);