Refinements for updated "Genode Foundations" book

- Improve API descriptions
- Remove obsolete Xml_node::value method (fixes #3323)
- Follow coding style 'const char' -> 'char const'
- Avoid '>>' when nesting templates (limitation of parse_cxx)

repos/base/include/base/allocator_avl.h

@@ -210,7 +210,7 @@ class Genode::Allocator_avl_base : public Range_allocator
 		/**
 		 * Clean up the allocator and detect dangling allocations
 		 *
-		 * This function is called at the destruction time of the allocator. It
+		 * This method is called at the destruction time of the allocator. It
 		 * makes sure that the allocator instance releases all memory obtained
 		 * from the meta-data allocator.
 		 */

repos/base/include/base/entrypoint.h

@@ -91,11 +91,11 @@ class Genode::Entrypoint : Noncopyable
 
 		Reconstructible<Signal_receiver> _sig_rec { };
 
-		Lock                               _deferred_signals_mutex { };
+		Lock                                _deferred_signals_mutex { };
-		List<List_element<Signal_context>> _deferred_signals { };
+		List<List_element<Signal_context> > _deferred_signals { };
 
 		void _handle_deferred_signals() { }
-		Constructible<Signal_handler<Entrypoint>> _deferred_signal_handler { };
+		Constructible<Signal_handler<Entrypoint> > _deferred_signal_handler { };
 
 		bool _suspended                = false;
 		void (*_suspended_callback) () = nullptr;
@@ -124,7 +124,7 @@ class Genode::Entrypoint : Noncopyable
 		 * resume mechanism.
 		 */
 		void _handle_suspend() { _suspended = true; }
-		Constructible<Genode::Signal_handler<Entrypoint>> _suspend_dispatcher { };
+		Constructible<Genode::Signal_handler<Entrypoint> > _suspend_dispatcher { };
 
 		void _dispatch_signal(Signal &sig);
 		void _defer_signal(Signal &sig);
@@ -136,7 +136,7 @@ class Genode::Entrypoint : Noncopyable
 		bool                               _stop_signal_proxy { false };
 
 		void _handle_stop_signal_proxy() { _stop_signal_proxy = true; }
-		Constructible<Genode::Signal_handler<Entrypoint>> _stop_signal_proxy_handler { };
+		Constructible<Genode::Signal_handler<Entrypoint> > _stop_signal_proxy_handler { };
 
 		friend class Startup;
 

repos/base/include/io_mem_session/io_mem_session.h

@@ -1,5 +1,5 @@
 /*
- * \brief  I/O-memory session interface
+ * \brief  Memory-mapped I/O session interface
  * \author Christian Helmuth
  * \date   2006-08-01
  */

repos/base/include/parent/parent.h

@@ -101,12 +101,12 @@ class Genode::Parent
 		/**
 		 * Emulation of the original synchronous root interface
 		 *
-		 * This function transparently spawns a proxy "root" entrypoint that
+		 * This method transparently spawns a proxy "root" entrypoint that
 		 * dispatches asynchronous session-management operations (as issued
 		 * by the parent) to the local root interfaces via component-local
 		 * RPC calls.
 		 *
-		 * The function solely exists for API compatibility.
+		 * The method solely exists for API compatibility.
 		 */
 		static void announce(Service_name const &service_name,
 		                     Root_capability service_root);

repos/base/include/util/fifo.h

@@ -22,7 +22,7 @@ namespace Genode {
 
 
 /**
- * Fifo queue
+ * First-in first-out (FIFO) queue
  *
  * \param QT  queue element type
  */
@@ -75,16 +75,13 @@ class Genode::Fifo
 		Fifo() { }
 
 		/**
-		 * If queue is not empty then call
+		 * Call 'func' of type 'void (QT&)' the head element
-		 * lambda 'func' of type 'void (QT&)'
-		 * with the head element
 		 */
 		template <typename FUNC>
-		void head(FUNC const &func) const {
+		void head(FUNC const &func) const { if (_head) func(*_head); }
-			if (_head) func(*_head); }
 
 		/**
-		 * Remove element explicitely from queue
+		 * Remove element explicitly from queue
 		 */
 		void remove(QT &qe)
 		{
@@ -93,9 +90,10 @@ class Genode::Fifo
 			/* if specified element is the first of the queue */
 			if (&qe == _head) {
 				_head = qe.Fifo::Element::_next;
-				if (!_head) _tail  = nullptr;
+				if (!_head)
-			}
+					_tail = nullptr;
-			else {
+
+			} else {
 
 				/* search specified element in the queue */
 				Element *e = _head;
@@ -131,10 +129,8 @@ class Genode::Fifo
 			_tail = &e;
 		}
 
-
 		/**
-		 * Call lambda 'func' of type 'void (QT&)'
+		 * Call 'func' of type 'void (QT&)' for each element in order
-		 * for each queue element in order
 		 */
 		template <typename FUNC>
 		void for_each(FUNC const &func) const
@@ -149,8 +145,7 @@ class Genode::Fifo
 		}
 
 		/**
-		 * If queue is not empty then remove head and
+		 * Remove head and call 'func' of type 'void (QT&)'
-		 * call lambda 'func' of type 'void (QT&)'
 		 */
 		template <typename FUNC>
 		void dequeue(FUNC const &func)
@@ -175,8 +170,11 @@ class Genode::Fifo
 		}
 
 		/**
-		 * If queue is not empty then remove elements in order and
+		 * Remove all fifo elements
-		 * call lambda 'func' of type 'void (QT&)'
+		 *
+		 * This method removes all elements in order and calls the lambda
+		 * 'func' of type 'void (QT&)' for each element. It is intended to be
+		 * used prior the destruction of the FIFO.
 		 */
 		template <typename FUNC>
 		void dequeue_all(FUNC const &func)
@@ -191,9 +189,9 @@ class Genode::Fifo
  *
  * \param T  type of compound object to be organized in a FIFO
  *
- * This helper allow the creation of FIFOs that use member variables to
+ * This helper allows the creation of FIFOs that use member variables to
  * connect their elements. This way, the organized type does not need to
- * publicly inherit 'Fifo<QT>::Element'. Furthermore objects can easily
+ * publicly inherit 'Fifo<QT>::Element'. Furthermore, objects can easily
  * be organized in multiple FIFOs by embedding multiple 'Fifo_element'
  * member variables.
  */

repos/base/include/util/xml_node.h

@@ -92,6 +92,9 @@ class Genode::Xml_attribute
 
 		/**
 		 * Return attribute type as null-terminated string
+		 *
+		 * \deprecated
+		 * \noapi
 		 */
 		void type(char *dst, size_t max_len) const
 		{
@@ -110,7 +113,7 @@ class Genode::Xml_attribute
 		/**
 		 * Return true if attribute has specified type
 		 */
-		bool has_type(const char *type) {
+		bool has_type(char const *type) {
 			return strlen(type) == _name.len() &&
 			       strcmp(type, _name.start(), _name.len()) == 0; }
 
@@ -118,6 +121,7 @@ class Genode::Xml_attribute
 		 * Return size of value
 		 *
 		 * \deprecated use 'with_raw_node' instead
+		 * \noapi
 		 */
 		char const *value_base() const { return _value.start() + 1; }
 
@@ -139,7 +143,7 @@ class Genode::Xml_attribute
 		/**
 		 * Return true if attribute has the specified value
 		 */
-		bool has_value(const char *value) const {
+		bool has_value(char const *value) const {
 			return strlen(value) == (_value.len() - 2)
 			    && !strcmp(value, _value.start() + 1, _value.len() - 2); }
 
@@ -165,6 +169,7 @@ class Genode::Xml_attribute
 		 * Return attribute value as null-terminated string
 		 *
 		 * \deprecated
+		 * \noapi
 		 */
 		void value(char *dst, size_t max_len) const
 		{
@@ -205,6 +210,7 @@ class Genode::Xml_attribute
 		 * Return attribute value as 'Genode::String'
 		 *
 		 * \deprecated  use 'value(String<N> &out' instead
+		 * \noapi
 		 */
 		template <size_t N>
 		void value(String<N> *out) const
@@ -217,6 +223,7 @@ class Genode::Xml_attribute
 		 * Return attribute value as typed value
 		 *
 		 * \deprecated  use 'value(T &out)' instead
+		 * \noapi
 		 */
 		template <typename T>
 		bool value(T *out) const
@@ -500,7 +507,7 @@ class Genode::Xml_node
 
 		int _num_sub_nodes { 0 }; /* number of immediate sub nodes */
 
-		const char * _addr;       /* first character of XML data */
+		char const * _addr;       /* first character of XML data */
 		size_t       _max_len;    /* length of XML data in characters */
 		Tag          _start_tag;
 		Tag          _end_tag;
@@ -560,9 +567,9 @@ class Genode::Xml_node
 				}
 
 				/* reaching the same depth as the start tag */
-				const char *start_name = start_tag.name().start();
+				char const *start_name = start_tag.name().start();
 				size_t      start_len  = start_tag.name().len();
-				const char *curr_name  =  curr_tag.name().start();
+				char const *curr_name  =  curr_tag.name().start();
 				size_t      curr_len   =  curr_tag.name().len();
 
 				/* on mismatch of start tag and end tag, return invalid tag */
@@ -610,7 +617,7 @@ class Genode::Xml_node
 		 * \throw Nonexistent_sub_node
 		 * \throw Invalid_syntax
 		 */
-		Xml_node _sub_node(const char *at) const
+		Xml_node _sub_node(char const *at) const
 		{
 			if (at < _addr || (size_t)(at - _addr) >= _max_len)
 				throw Nonexistent_sub_node();
@@ -633,7 +640,7 @@ class Genode::Xml_node
 		 *
 		 * \throw Invalid_syntax
 		 */
-		Xml_node(const char *addr, size_t max_len = ~0UL)
+		Xml_node(char const *addr, size_t max_len = ~0UL)
 		:
 			_addr(addr),
 			_max_len(max_len),
@@ -649,6 +656,8 @@ class Genode::Xml_node
 
 		/**
 		 * Request type name of XML node as null-terminated string
+		 *
+		 * \noapi
 		 */
 		void type_name(char *dst, size_t max_len) const {
 			_start_tag.name().string(dst, max_len); }
@@ -662,6 +671,7 @@ class Genode::Xml_node
 		 * Return pointer to start of node
 		 *
 		 * \deprecated  use 'with_raw_node' instead
+		 * \noapi
 		 */
 		char const *addr() const { return _addr; }
 
@@ -689,7 +699,7 @@ class Genode::Xml_node
 		/**
 		 * Return true if tag is of specified type
 		 */
-		bool has_type(const char *type) const {
+		bool has_type(char const *type) const {
 			return (!strcmp(type, _start_tag.name().start(),
 			                      _start_tag.name().len())
 			      && strlen(type) == _start_tag.name().len()); }
@@ -738,13 +748,6 @@ class Genode::Xml_node
 		 */
 		char const *content_base() const { return content_addr(); }
 
-		/**
-		 * Return content as out value
-		 *
-		 * \deprecated  use with_raw_content instead
-		 */
-		template <typename T> bool value(T *out) const { return value(*out); }
-
 		/**
 		 * Export decoded node content from XML node
 		 *
@@ -794,7 +797,7 @@ class Genode::Xml_node
 		/**
 		 * Return XML node following the current one
 		 *
-		 * \throw Nonexistent_sub_node  sub sequent node does not exist
+		 * \throw Nonexistent_sub_node  subsequent node does not exist
 		 */
 		Xml_node next() const
 		{
@@ -808,8 +811,10 @@ class Genode::Xml_node
 		 * Return next XML node of specified type
 		 *
 		 * \param type  type of XML node, or nullptr for matching any type
+		 *
+		 * \throw Nonexistent_sub_node  subsequent node does not exist
 		 */
-		Xml_node next(const char *type) const
+		Xml_node next(char const *type) const
 		{
 			Xml_node node = next();
 			for (; type && !node.has_type(type); node = node.next());
@@ -819,7 +824,7 @@ class Genode::Xml_node
 		/**
 		 * Return true if node is the last of a node sequence
 		 */
-		bool last(const char *type = 0) const
+		bool last(char const *type = 0) const
 		{
 			try { next(type); return false; }
 			catch (Nonexistent_sub_node) { return true; }
@@ -851,9 +856,9 @@ class Genode::Xml_node
 		/**
 		 * Return first sub node that matches the specified type
 		 *
-		 * \throw Nonexistent_sub_node  no such sub_node exists
+		 * \throw Nonexistent_sub_node  no such sub node exists
 		 */
-		Xml_node sub_node(const char *type) const
+		Xml_node sub_node(char const *type) const
 		{
 			if (_num_sub_nodes > 0) {
 
@@ -940,7 +945,7 @@ class Genode::Xml_node
 		 * \throw Nonexistent_attribute  no such attribute exists
 		 * \return                       XML attribute
 		 */
-		Xml_attribute attribute(const char *type) const
+		Xml_attribute attribute(char const *type) const
 		{
 			/* iterate, beginning with the first attribute of the node */
 			for (Xml_attribute a = _start_tag.attribute(); ; a = a.next())

repos/os/include/block_session/connection.h

@@ -189,7 +189,7 @@ struct Block::Connection : Genode::Connection<Session>, Session_client
 		/**
 		 * Jobs that are pending for submission
 		 */
-		Genode::Fifo<Genode::Fifo_element<_JOB>> _pending { };
+		Genode::Fifo<Genode::Fifo_element<_JOB> > _pending { };
 
 		/**
 		 * Process a single acknowledgement