add documentation comments

3 files changed, 24 insertions, 3 deletions

diff --git a/vespalib/src/vespa/vespalib/util/reusable_set.h b/vespalib/src/vespa/vespalib/util/reusable_set.h
index 1896b171e88..92a68a68bd6 100644
--- a/vespalib/src/vespa/vespalib/util/reusable_set.h
+++ b/vespalib/src/vespa/vespalib/util/reusable_set.h
@@ -10,7 +10,12 @@
 
 namespace vespalib {
 
+/**
+ * Generational marker implementation of a vector of boolean values.
+ * Limited API, used for marking "seen" nodes when exploring a graph.
+ **/
 class ReusableSet
+
 {
 public:
     using Mark = unsigned short;
@@ -26,6 +31,10 @@ public:
     ~ReusableSet() {
     }
 
+    /**
+     * Increments the generation value, only
+     * initializing the underlying memory when it wraps
+     **/
     void clear() {
         if (++_curval == 0) {
             memset(bits(), 0, _sz * sizeof(Mark));
@@ -42,15 +51,13 @@ public:
     }
 
     Mark *bits() { return _array.begin(); }
-
     Mark generation() const { return _curval; }
+    size_t capacity() const { return _sz; }
 
     size_t memory_usage() const {
         return (_sz * sizeof(Mark)) + sizeof(ReusableSet);
     }
 
-    size_t capacity() const { return _sz; }
-
 private:
     Array<Mark> _array;
     Mark _curval;
diff --git a/vespalib/src/vespa/vespalib/util/reusable_set_handle.h b/vespalib/src/vespa/vespalib/util/reusable_set_handle.h
index 386370bdd62..be230fdc60d 100644
--- a/vespalib/src/vespa/vespalib/util/reusable_set_handle.h
+++ b/vespalib/src/vespa/vespalib/util/reusable_set_handle.h
@@ -8,6 +8,11 @@ namespace vespalib {
 
 class ReusableSetPool;
 
+/**
+ * Wraps a ReusableSet allocated from a ReusableSetPool.
+ * Note that the handle returns the wrapped set to the pool
+ * on destruction.
+ **/
 class ReusableSetHandle
 {
 private:
@@ -29,10 +34,12 @@ public:
 
     ~ReusableSetHandle();
 
+    /** mark an ID */
     void mark(size_t id) {
         _bits[id] = _curval;
     }
 
+    /** check if an ID has been marked */
     bool is_marked(size_t id) const {
         return (_bits[id] == _curval);
     }
diff --git a/vespalib/src/vespa/vespalib/util/reusable_set_pool.h b/vespalib/src/vespa/vespalib/util/reusable_set_pool.h
index e5e9d4e64d7..7e3562a3d72 100644
--- a/vespalib/src/vespa/vespalib/util/reusable_set_pool.h
+++ b/vespalib/src/vespa/vespalib/util/reusable_set_pool.h
@@ -10,6 +10,11 @@
 
 namespace vespalib {
 
+/**
+ * A resource pool for ReusableSet instances.
+ * Note that the pool should have a guaranteed lifetime
+ * that is longer than any Handle retrieved from the pool.
+ **/
 class ReusableSetPool
 {
     using RSUP = std::unique_ptr<ReusableSet>;
@@ -33,6 +38,7 @@ public:
         _min_size(248), _grow_percent(20)
     {}
 
+    /** Create or re-use a set with (at least) the given size. */
     ReusableSetHandle get(size_t size) {
         Guard guard(_lock);
         size_t last_used_size = 0;
@@ -56,6 +62,7 @@ public:
         return ReusableSetHandle(std::move(r), *this);
     }
 
+    /** Return a ReusableSet to the pool. */
     void reuse(RSUP used) {
         Guard guard(_lock);
         _lru_stack.push_back(std::move(used));