doc: tweaks for updated Genode Foundations book

repos/base/include/base/blockade.h

@@ -1,7 +1,15 @@
 /*
- * \brief  Blockade primitives
+ * \brief  Blockade primitive
  * \author Alexander Boettcher
  * \date   2020-01-24
+ *
+ * A 'Blockade' is a locking primitive designated for deliberately pausing
+ * the execution of a thread until woken up by another thread. It is typically
+ * used as a mechanism for synchonizing the startup of threads.
+ *
+ * At initialization time, a blockade is in locked state. A thread can pause
+ * its own execution by calling the 'block()' method. Another thread can wake
+ * up the paused thread by calling 'wakeup()' on the blockade.
  */
 
 /*
@@ -23,10 +31,12 @@ namespace Genode { class Blockade; }
 class Genode::Blockade : Noncopyable
 {
 	private:
+
 		Lock _lock;
 
 	public:
-		explicit Blockade() : _lock(Lock::LOCKED) { }
+
+		Blockade() : _lock(Lock::LOCKED) { }
 
 		void block() { _lock.lock(); }
 

repos/base/include/base/log.h

@@ -174,11 +174,11 @@ namespace Genode {
 	void raw(ARGS &&... args) { Raw::output(args...); }
 
 
-  /**
-   * Write 'args' to the trace buffer if tracing is enabled
-   *
-   * The message is prefixed with a timestamp value
-   */
+	/**
+	 * Write 'args' to the trace buffer if tracing is enabled
+	 *
+	 * The message is prefixed with a timestamp value
+	 */
 	template <typename... ARGS>
 	void trace(ARGS && ... args) {
 		Trace_output::trace_output().output(Trace::timestamp(), ": ", args...); }

repos/base/include/base/mutex.h

@@ -1,7 +1,25 @@
 /*
- * \brief  Mutex primitives
+ * \brief  Mutex primitive
  * \author Alexander Boettcher
  * \date   2020-01-24
+ *
+ * A 'Mutex' is a locking primitive designated for the mutual exclusion of
+ * multiple threads executing a critical section, which is typically code that
+ * mutates a shared variable.
+ *
+ * At initialization time, a mutex is in unlocked state. To enter and leave a
+ * critical section, the methods 'acquire()' and 'release()' are provided.
+ *
+ * A mutex must not be used recursively. The subsequential attempt of aquiring
+ * a mutex twice by the same thread ultimately results in a deadlock. This
+ * misbehavior generates a warning message at runtime.
+ *
+ * Only the thread that aquired the mutex is permitted to release the mutex.
+ * The violation of this invariant generates a warning message and leaves the
+ * mutex unchanged.
+ *
+ * A 'Mutex::Guard' is provided, which acquires a mutex at construction time
+ * and releases it automatically at the destruction time of the guard.
  */
 
 /*
@@ -23,10 +41,12 @@ namespace Genode { class Mutex; }
 class Genode::Mutex : Noncopyable
 {
 	private:
+
 		Lock _lock { };
 
 	public:
-		explicit Mutex() { }
+
+		Mutex() { }
 
 		void acquire();
 		void release();
@@ -34,9 +54,11 @@ class Genode::Mutex : Noncopyable
 		class Guard
 		{
 			private:
+
 				Mutex &_mutex;
 
 			public:
+
 				explicit Guard(Mutex &mutex) : _mutex(mutex) { _mutex.acquire(); }
 
 				~Guard() { _mutex.release(); }

repos/base/include/base/thread.h

@@ -332,6 +332,9 @@ class Genode::Thread
 
 		/**
 		 * Cancel currently blocking operation
+		 *
+		 * \deprecated
+		 * \noapi
 		 */
 		void cancel_blocking();
 

repos/base/include/cpu_thread/cpu_thread.h

@@ -57,6 +57,9 @@ struct Genode::Cpu_thread : Interface
 
 	/**
 	 * Cancel a currently blocking operation
+	 *
+	 * \deprecated
+	 * \noapi
 	 */
 	virtual void cancel_blocking() = 0;
 

repos/base/include/util/xml_node.h

@@ -1123,6 +1123,13 @@ class Genode::Xml_node
 };
 
 
+/**
+ * Utility for unquoting XML attributes
+ *
+ * The 'Xml_unquoted' utility can be used to revert quoted XML attribute
+ * values. Such quoting is needed whenever an attribute value can contain '"'
+ * characters.
+ */
 class Genode::Xml_unquoted : Noncopyable
 {
 	private:

repos/os/include/block_session/connection.h

@@ -2,6 +2,20 @@
  * \brief  Connection to block service
  * \author Norman Feske
  * \date   2019-04-10
+ *
+ * The 'Block::Connection' is equipped with an interface for the implementation
+ * of robust block-session clients that perform block I/O in an asynchronous
+ * fashion.
+ *
+ * An application-defined JOB type, inherited from 'Connection::Job',
+ * encapsulates the application's context information associated with a block
+ * operation.
+ *
+ * The life cycle of the jobs is implemented by the 'Connection' and driven by
+ * the application's invocation of 'Connection::update_jobs'. The 'update_jobs'
+ * mechanism takes three hook functions as arguments, which implement the
+ * applications-defined policy for producing and consuming data, and for the
+ * completion of jobs.
  */
 
 /*