update thread_pool docs

Author: duck2

libs/libvtrutil/src/vtr_thread_pool.h

@@ -3,18 +3,6 @@
 /** 
  * @file vtr_thread_pool.h
  * @brief A generic thread pool for parallel task execution
- *
- * A thread pool for parallel task execution. It is a naive
- * implementation which uses a queue for each thread and assigns
- * tasks in a round robin fashion.
- *
- * Example usage:
- *
- * vtr::thread_pool pool(4);
- * pool.schedule_work([]{
- *     // Task body
- * });
- * pool.wait_for_all(); // There's no API to wait for a single task
  */
 
 #include <thread>
@@ -31,6 +19,21 @@
 
 namespace vtr {
 
+/**
+ * A thread pool for parallel task execution. It is a naive
+ * implementation which uses a queue for each thread and assigns
+ * tasks in a round robin fashion.
+ *
+ * Example usage:
+ *
+ * ```
+ * vtr::thread_pool pool(4);  // 4 threads
+ * pool.schedule_work([]{
+ *     // Task body
+ * });
+ * pool.wait_for_all();  // There's no API to wait for a single task
+ * ```
+ */
 class thread_pool {
   private:
     /** Thread-local data */
@@ -58,6 +61,7 @@ class thread_pool {
     std::condition_variable completion_cv;
 
   public:
+    /** Create a thread pool with \p thread_count threads. */
     thread_pool(size_t thread_count) {
         threads.reserve(thread_count);
 
@@ -95,6 +99,7 @@ class thread_pool {
         }
     }
 
+    /** Schedule a function to be executed on one of the threads. */
     template<typename F>
     void schedule_work(F&& f) {
         active_tasks++;
@@ -132,6 +137,8 @@ class thread_pool {
         thread_data->cv.notify_one();
     }
 
+    /** Wait until the work queue is empty.
+     * Note that functions are allowed to schedule new functions. */
     void wait_for_all() {
         std::unique_lock<std::mutex> lock(completion_mutex);
         completion_cv.wait(lock, [this]() { return active_tasks == 0; });