Make API documentation of thread pools visible

* include/abg-workers.h: Document the workers namespace, the task,
	queue and queue::task_done_notify types.
	* src/abg-workers.cc: Move the documentation of the thread_pool
	module inside the abigail::worker namespace, so that references to
	task and queue types (which are also in the abigail::worker
	namespace) can be resolved in the apidoc.

Signed-off-by: Dodji Seketeli <dodji@redhat.com>

include/abg-workers.h

@@ -38,6 +38,10 @@ using std::tr1::shared_ptr;
 
 namespace abigail
 {
+
+/// The namespace of the worker threads (or thread pool)
+/// implementation of libabigail.  This was modelled after the article
+/// https://en.wikipedia.org/wiki/Thread_pool.
 namespace workers
 {
 
@@ -46,6 +50,13 @@ typedef shared_ptr<task> task_sptr;
 
 size_t get_number_of_threads();
 
+/// This represents a task to be performed.
+///
+/// Each instance of this type represents a task that can be performed
+/// concurrently to other instance of the same type.
+///
+/// An instance of @ref task is meant to be performed by a worker
+/// (thread).  A set of tasks can be stored in a @ref queue.
 class task
 {
 public:
@@ -56,6 +67,20 @@ public:
   virtual ~task();
 }; // end class task.
 
+/// This represents a queue of tasks to be performed.
+///
+/// Tasks are performed by a number of worker threads.
+///
+/// When a task is inserted into a @ref queue, the task is said to be
+/// "scheduled for execution".
+///
+/// This is because there are worker threads waiting for tasks to be
+/// added to the queue.  When a task is added to the queue, a worker
+/// thread picks it up, executes it, notifies interested listeners
+/// when the @ref task's execution is completed, and waits for another
+/// task to be added to the queue.
+///
+/// Of course, several worker threads can execute tasks concurrently.
 class queue
 {
 public:
@@ -78,6 +103,8 @@ public:
   ~queue();
 }; // end class queue
 
+/// This functor is to notify listeners that a given task scheduled
+/// for execution has been fully executed.
 struct queue::task_done_notify
 {
   virtual void

src/abg-workers.cc

@@ -26,24 +26,40 @@
 /// pattern.  It aims at performing a set of tasks in parallel, using
 /// the multi-threading capabilities of the underlying processor(s).
 
-/// @defgroup Worker Threads
+#include <assert.h>
+#include <unistd.h>
+#include <pthread.h>
+#include <queue>
+#include <vector>
+#include <iostream>
+#include "abg-workers.h"
+namespace abigail
+{
+
+namespace workers
+{
+
+/// @defgroup thread_pool Worker Threads
 /// @{
 ///
-/// The main interface of this pattern is a queue of tasks to be
-/// performed.  Associated to that queue are a set of worker threads,
-/// that sit there, idle, until at least one task is added to the
-/// queue.
+/// \brief Libabigail's implementation of Thread Pools.
 ///
-/// When a task is added to the queue, one thread is woken up, picks
-/// the task, removes it from the queue, and executes the instructions
-/// carried by the task.  We say the worker thread performs the task.
+/// The main interface of this pattern is a @ref queue of @ref tasks
+/// to be performed.  Associated to that queue are a set of worker
+/// threads (these are native posix threads) that sits there, idle,
+/// until at least one @ref task is added to the queue.
 ///
-/// When the worker thread is done performing the task, the performed
-/// task is added to another queue, named as the "done queue".  Then
-/// the thread looks at the queue of tasks to be performed again, and
-/// if there is at least one task in that queue, the same process as
-/// above is done.  Otherwise, the thread blocks, waiting for a new
-/// task to be added to the queue.
+/// When a @ref task is added to the @ref queue, one thread is woken
+/// up, picks the @ref task, removes it from the @ref queue, and
+/// executes the instructions it carries.  We say the worker thread
+/// performs the @ref task.
+///
+/// When the worker thread is done performing the @ref task, the
+/// performed @ref task is added to another queue, named as the "done
+/// queue".  Then the thread looks at the @ref queue of tasks to be
+/// performed again, and if there is at least one task in that queue,
+/// the same process as above is done.  Otherwise, the thread blocks,
+/// waiting for a new task to be added to the queue.
 ///
 /// By default, the number of worker threads is equal to the number of
 /// execution threads advertised by the underlying processor.
@@ -58,18 +74,6 @@
 ///
 ///@}
 
-#include <assert.h>
-#include <unistd.h>
-#include <pthread.h>
-#include <queue>
-#include <vector>
-#include <iostream>
-#include "abg-workers.h"
-namespace abigail
-{
-namespace workers
-{
-
 /// @return The number of hardware threads of executions advertised by
 /// the underlying processor.
 size_t