Revised API documentation

This patch curates the API documentation to become suitable for the
functional specificaton, which is partially generated from the header
files.

repos/base/include/32bit/base/fixed_stdint.h

@@ -1,5 +1,5 @@
 /*
- * \brief  Standard fixed-width integer types
+ * \brief  Fixed-width integer types for 32-bit architectures
  * \author Christian Helmuth
  * \author Norman Feske
  * \date   2006-05-10
@@ -28,9 +28,10 @@
 #define _INCLUDE__32BIT__BASE__FIXED_STDINT_H_
 
 
-/*
+/**********************************************************
- * Fixed-size types usable from both C and C++ programs
+ ** Fixed-size types usable from both C and C++ programs **
- */
+ **********************************************************/
+
 typedef signed char        genode_int8_t;
 typedef unsigned char      genode_uint8_t;
 typedef signed short       genode_int16_t;
@@ -41,9 +42,10 @@ typedef signed long long   genode_int64_t;
 typedef unsigned long long genode_uint64_t;
 
 
-/*
+/**************************************************
- * Types residing within Genode's C++ namespace
+ ** Types residing within Genode's C++ namespace **
- */
+ **************************************************/
+
 #ifdef __cplusplus
 namespace Genode {
 	typedef genode_int8_t     int8_t;

repos/base/include/64bit/base/fixed_stdint.h

@@ -1,5 +1,5 @@
 /*
- * \brief  Standard fixed-width integer types
+ * \brief  Fixed-width integer types for 64-bit architectures
  * \author Christian Helmuth
  * \author Norman Feske
  * \date   2006-05-10
@@ -18,9 +18,10 @@
 #define _INCLUDE__64BIT__BASE__FIXED_STDINT_H_
 
 
-/*
+/**********************************************************
- * Fixed-size types usable from both C and C++ programs
+ ** Fixed-size types usable from both C and C++ programs **
- */
+ **********************************************************/
+
 typedef signed char        genode_int8_t;
 typedef unsigned char      genode_uint8_t;
 typedef signed short       genode_int16_t;
@@ -31,9 +32,10 @@ typedef signed long long   genode_int64_t;
 typedef unsigned long long genode_uint64_t;
 
 
-/*
+/**************************************************
- * Types residing within Genode's C++ namespace
+ ** Types residing within Genode's C++ namespace **
- */
+ **************************************************/
+
 #ifdef __cplusplus
 namespace Genode {
 	typedef genode_int8_t     int8_t;

repos/base/include/base/affinity.h

@@ -79,7 +79,7 @@ class Genode::Affinity
 				 * Return the location of the Nth CPU within the affinity
 				 * space
 				 *
-				 * This function returns a valid location even if the index
+				 * This method returns a valid location even if the index
 				 * is larger than the number of CPUs in the space. In this
 				 * case, the x and y coordinates are wrapped by the bounds
 				 * of the space.

repos/base/include/base/allocator.h

@@ -23,27 +23,13 @@ namespace Genode {
 	struct Allocator;
 	struct Range_allocator;
 
-	/**
-	 * Destroy object
-	 *
-	 * For destroying an object, we need to specify the allocator that was used
-	 * by the object. Because we cannot pass the allocator directly to the
-	 * delete expression, we mimic the expression by using this template
-	 * function. The function explicitly calls the object destructor and
-	 * operator delete afterwards.
-	 *
-	 * For details see https://github.com/genodelabs/genode/issues/1030.
-	 *
-	 * \param T        implicit object type
-	 *
-	 * \param dealloc  reference or pointer to allocator from which the object
-	 *                 was allocated
-	 * \param obj      object to destroy
-	 */
 	template <typename T, typename DEALLOC> void destroy(DEALLOC && dealloc, T *obj);
 }
 
 
+/**
+ * Deallocator interface
+ */
 struct Genode::Deallocator
 {
 	/**
@@ -56,7 +42,7 @@ struct Genode::Deallocator
 	 *
 	 * The generic 'Allocator' interface requires the caller of 'free'
 	 * to supply a valid size argument but not all implementations make
-	 * use of this argument. If this function returns false, it is safe
+	 * use of this argument. If this method returns false, it is safe
 	 * to call 'free' with an invalid size.
 	 *
 	 * Allocators that rely on the size argument must not be used for
@@ -94,7 +80,7 @@ struct Genode::Allocator : Deallocator
 	 * Allocate typed block
 	 *
 	 * This template allocates a typed block returned as a pointer to
-	 * a non-void type. By providing this function, we prevent the
+	 * a non-void type. By providing this method, we prevent the
 	 * compiler from warning us about "dereferencing type-punned
 	 * pointer will break strict-aliasing rules".
 	 */
@@ -116,11 +102,6 @@ struct Genode::Allocator : Deallocator
 	 */
 	virtual size_t overhead(size_t size) = 0;
 
-
-	/***************************
-	 ** Convenience functions **
-	 ***************************/
-
 	/**
 	 * Allocate block and signal error as an exception
 	 *
@@ -199,7 +180,7 @@ struct Genode::Range_allocator : Allocator
 	/**
 	 * Free a previously allocated block
 	 *
-	 * NOTE: We have to declare the 'Allocator::free(void *)' function
+	 * NOTE: We have to declare the 'Allocator::free(void *)' method
 	 * here as well to make the compiler happy. Otherwise the C++
 	 * overload resolution would not find 'Allocator::free(void *)'.
 	 */
@@ -255,14 +236,30 @@ void *operator new [] (Genode::size_t, Genode::Allocator &);
  * we print a warning and pass the zero size argument anyway.
  *
  * :Warning: Never use an allocator that depends on the size argument of the
- *   'free()' function for the allocation of objects that may throw exceptions
+ *   'free()' method for the allocation of objects that may throw exceptions
  *   at their construction time!
  */
 void operator delete (void *, Genode::Deallocator *);
 void operator delete (void *, Genode::Deallocator &);
 
 
-/* implemented here as it needs the special delete operators */
+/**
+ * Destroy object
+ *
+ * For destroying an object, we need to specify the allocator that was used
+ * by the object. Because we cannot pass the allocator directly to the
+ * delete expression, we mimic the expression by using this template
+ * function. The function explicitly calls the object destructor and
+ * operator delete afterwards.
+ *
+ * For details see https://github.com/genodelabs/genode/issues/1030.
+ *
+ * \param T        implicit object type
+ *
+ * \param dealloc  reference or pointer to allocator from which the object
+ *                 was allocated
+ * \param obj      object to destroy
+ */
 template <typename T, typename DEALLOC>
 void Genode::destroy(DEALLOC && dealloc, T *obj)
 {

repos/base/include/base/allocator_avl.h

@@ -2,10 +2,6 @@
  * \brief  Interface of AVL-tree-based allocator
  * \author Norman Feske
  * \date   2006-04-16
- *
- * Each block of the managed address space is present in two AVL trees,
- * one tree ordered by the base addresses of the blocks and one tree ordered
- * by the available capacity within the block.
  */
 
 /*
@@ -149,9 +145,17 @@ class Genode::Allocator_avl_base : public Range_allocator
 				size_t avail_in_subtree(void);
 
 				/**
-				 * Debug hooks
+				 * Debug hook
+				 *
+				 * \noapi
 				 */
 				void dump();
+
+				/**
+				 * Debug hook
+				 *
+				 * \noapi
+				 */
 				void dump_dot(int indent = 0);
 		};
 
@@ -230,6 +234,8 @@ class Genode::Allocator_avl_base : public Range_allocator
 
 		/**
 		 * Debug hook
+		 *
+		 * \noapi
 		 */
 		void dump_addr_tree(Block *addr_node = 0);
 

repos/base/include/base/blocking.h

@@ -2,13 +2,6 @@
  * \brief  Support for blocking operations
  * \author Norman Feske
  * \date   2007-09-06
- *
- * In Genode, two operations may block a thread,
- * waiting at a lock or performing an IPC call.
- * Both operations may be canceled when killing
- * the thread. In this case, the thread unblocks
- * and throws an exception, and therefore, is able
- * to clean up the thread state before exiting.
  */
 
 /*
@@ -25,6 +18,14 @@
 
 namespace Genode { class Blocking_canceled; }
 
+/**
+ * Blocking-canceled exception
+ *
+ * Two operations may block a thread, waiting at a lock or performing an RPC
+ * call. Both operations may be canceled when the thread is destructed. In this
+ * case, the thread unblocks and throws an exception, and therefore, is able to
+ * clean up the thread state before exiting.
+ */
 class Genode::Blocking_canceled : public Exception { };
 
 #endif /* _INCLUDE__BASE__BLOCKING_H_ */

repos/base/include/base/cancelable_lock.h

@@ -77,9 +77,9 @@ class Genode::Cancelable_lock
 		explicit Cancelable_lock(State initial = UNLOCKED);
 
 		/**
-		 * Try to aquire lock an block while lock is not free
+		 * Try to aquire the lock and block while the lock is not free
 		 *
-		 * This function may throw a Genode::Blocking_canceled exception.
+		 * \throw  Genode::Blocking_canceled
 		 */
 		void lock();
 

repos/base/include/base/capability.h

@@ -90,7 +90,7 @@ class Genode::Capability : public Untyped_capability
 		 * A server-side exception is indicated by a non-zero exception
 		 * code. Each exception code corresponds to an entry in the
 		 * exception type list specified in the RPC function declaration.
-		 * The '_check_for_exception' function template throws the
+		 * The '_check_for_exception' method template throws the
 		 * exception type belonging to the received exception code.
 		 */
 		template <typename EXC_TL>
@@ -117,7 +117,7 @@ class Genode::Capability : public Untyped_capability
 		           typename IF::Ret_type    &ret) const;
 
 		/**
-		 * Shortcut for querying argument types used in 'call' functions
+		 * Shortcut for querying argument types used in 'call' methods
 		 */
 		template <typename IF, unsigned I>
 		struct Arg
@@ -148,7 +148,7 @@ class Genode::Capability : public Untyped_capability
 		 *
 		 * Each 'call' overload creates an instance of the return value
 		 * type as local variable. A reference to this variable is passed
-		 * to the '_call' function, which will assign its value. Even
+		 * to the '_call' method, which will assign its value. Even
 		 * though the variable does not need to be initialized prior the
 		 * call of '_call', the GCC will still complain "warning: ‘ret’ may
 		 * be used uninitialized in this function". Wrapping the return

repos/base/include/base/child.h

@@ -105,7 +105,7 @@ struct Genode::Child_policy
 	/**
 	 * Reference RAM session
 	 *
-	 * The RAM session returned by this function is used for session-quota
+	 * The RAM session returned by this method is used for session-quota
 	 * transfers.
 	 */
 	virtual Ram_session *ref_ram_session() { return env()->ram_session(); }
@@ -113,7 +113,7 @@ struct Genode::Child_policy
 	/**
 	 * Return platform-specific PD-session arguments
 	 *
-	 * This function is used on Linux to supply additional PD-session
+	 * This method is used on Linux to supply additional PD-session
 	 * argument to core, i.e., the chroot path, the UID, and the GID.
 	 */
 	virtual Native_pd_args const *pd_args() const { return 0; }
@@ -121,7 +121,7 @@ struct Genode::Child_policy
 	/**
 	 * Respond to the release of resources by the child
 	 *
-	 * This function is called when the child confirms the release of
+	 * This method is called when the child confirms the release of
 	 * resources in response to a yield request.
 	 */
 	virtual void yield_response() { }
@@ -137,14 +137,11 @@ struct Genode::Child_policy
  * Implementation of the parent interface that supports resource trading
  *
  * There are three possible cases of how a session can be provided to
- * a child:
+ * a child: The service is implemented locally, the session was obtained by
- *
+ * asking our parent, or the session is provided by one of our children.
- * # The service is implemented locally
- * # The session was obtained by asking our parent
- * # The session is provided by one of our children
  *
  * These types must be differentiated for the quota management when a child
- * issues the closing of a session or a transfers quota via our parent
+ * issues the closing of a session or transfers quota via our parent
  * interface.
  *
  * If we close a session to a local service, we transfer the session quota
@@ -154,7 +151,7 @@ struct Genode::Child_policy
  * account and must transfer this amount to the session-closing child.
  *
  * If we close a session provided by a server child, we close the session
- * at the server, transfer the session quota from the server's ram session
+ * at the server, transfer the session quota from the server's RAM session
  * to our account, and subsequently transfer the same amount from our
  * account to the client.
  */
@@ -225,7 +222,7 @@ class Genode::Child : protected Rpc_object<Parent>
 		/**
 		 * Return service interface targetting the parent
 		 *
-		 * The service returned by this function is used as default
+		 * The service returned by this method is used as default
 		 * provider for the RAM, CPU, and RM resources of the child. It is
 		 * solely used for targeting resource donations during
 		 * 'Parent::upgrade_quota()' calls.
@@ -290,7 +287,7 @@ class Genode::Child : protected Rpc_object<Parent>
 		/**
 		 * Discard all sessions to specified service
 		 *
-		 * When this function is called, we assume the server protection
+		 * When this method is called, we assume the server protection
 		 * domain to be dead and all that all server quota was already
 		 * transferred back to our own 'env()->ram_session()' account. Note
 		 * that the specified server object may not exist anymore. We do
@@ -301,7 +298,7 @@ class Genode::Child : protected Rpc_object<Parent>
 		/**
 		 * Instruct the child to yield resources
 		 *
-		 * By calling this function, the child will be notified about the
+		 * By calling this method, the child will be notified about the
 		 * need to release the specified amount of resources. For more
 		 * details about the protocol between a child and its parent,
 		 * refer to the description given in 'parent/parent.h'.

repos/base/include/base/connection.h

@@ -65,6 +65,13 @@ class Genode::Connection : public Noncopyable
 		 *
 		 * \param cap  session capability
 		 * \param od   session policy applied when destructing the connection
+		 *
+		 * The 'op' argument defines whether the session should automatically
+		 * be closed by the destructor of the connection (CLOSE), or the
+		 * session should stay open (KEEP_OPEN). The latter is useful in
+		 * situations where the creator a connection merely passes the
+		 * session capability of the connection to another party but never
+		 * invokes any of the session's RPC functions.
 		 */
 		Connection(Capability<SESSION_TYPE> cap, On_destruction od = CLOSE):
 			_cap(cap), _on_destruction(od) { }

repos/base/include/base/console.h

@@ -34,18 +34,18 @@ class Genode::Console
 	protected:
 
 		/**
-		 * Backend function for the output of one character
+		 * Back end used for the output of a single character
 		 */
 		virtual void _out_char(char c) = 0;
 
 		/**
-		 * Backend function for the output of a null-terminated string
+		 * Back end for the output of a null-terminated string
 		 *
-		 * The default implementation uses _out_char. This function may
+		 * The default implementation uses _out_char. This method may
 		 * be overridden by the backend for improving efficiency.
 		 *
-		 * This function is virtual to enable the use an optimized
+		 * This method is virtual to enable the use an optimized
-		 * string-output functions on some target platforms, e.g.
+		 * string-output operation on some target platforms, e.g.,
 		 * a kernel debugger that offers a string-output syscall. The
 		 * default implementation calls '_out_char' for each character.
 		 */

repos/base/include/base/env.h

@@ -1,10 +1,7 @@
 /*
- * \brief  Environment of a process
+ * \brief  Environment of a component
  * \author Norman Feske
  * \date   2006-07-01
- *
- * The environment of a Genode process is defined by its parent and initialized
- * on startup.
  */
 
 /*

repos/base/include/base/heap.h

@@ -30,7 +30,7 @@ namespace Genode {
 /**
  * Heap that uses dataspaces as backing store
  *
- * The heap class provides an allocator that uses a list of dataspaces of a ram
+ * The heap class provides an allocator that uses a list of dataspaces of a RAM
  * session as backing store. One dataspace may be used for holding multiple blocks.
  */
 class Genode::Heap : public Allocator
@@ -76,7 +76,7 @@ class Genode::Heap : public Allocator
 		 */
 		struct Dataspace_pool : public List<Dataspace>
 		{
-			Ram_session *ram_session; /* ram session for backing store */
+			Ram_session *ram_session; /* RAM session for backing store */
 			Rm_session  *rm_session;  /* region manager */
 
 			Dataspace_pool(Ram_session *ram_session, Rm_session *rm_session)
@@ -120,7 +120,7 @@ class Genode::Heap : public Allocator
 		 *
 		 * \return true on success
 		 *
-		 * This function is a utility used by '_unsynchronized_alloc' to
+		 * This method is a utility used by '_unsynchronized_alloc' to
 		 * avoid code duplication.
 		 */
 		bool _try_local_alloc(size_t size, void **out_addr);
@@ -185,7 +185,7 @@ class Genode::Sliced_heap : public Allocator
 
 		class Block;
 
-		Ram_session    *_ram_session;  /* ram session for backing store */
+		Ram_session    *_ram_session;  /* RAM session for backing store */
 		Rm_session     *_rm_session;   /* region manager                */
 		size_t          _consumed;     /* number of allocated bytes     */
 		List<Block>     _block_list;   /* list of allocated blocks      */

repos/base/include/base/ipc.h

@@ -295,7 +295,7 @@ class Genode::Ipc_ostream : public Ipc_marshaller
 		/**
 		 * Return current 'IPC_SEND' destination
 		 *
-		 * This function is typically needed by a server than sends replies
+		 * This method is typically needed by a server than sends replies
 		 * in a different order as the incoming calls.
 		 */
 		Native_capability dst() const { return _dst; }
@@ -535,7 +535,7 @@ class Genode::Ipc_server : public Ipc_istream, public Ipc_ostream
 		/**
 		 * Wait for incoming call
 		 *
-		 * In constrast to 'Ipc_istream::_wait()', this function stores the
+		 * In constrast to 'Ipc_istream::_wait()', this method stores the
 		 * next reply destination from into 'dst' of the 'Ipc_ostream'.
 		 */
 		void _wait();
@@ -543,7 +543,7 @@ class Genode::Ipc_server : public Ipc_istream, public Ipc_ostream
 		/**
 		 * Send reply to destination
 		 *
-		 * In contrast to 'Ipc_ostream::_send()', this function prepares
+		 * In contrast to 'Ipc_ostream::_send()', this method prepares
 		 * the 'Ipc_server' to send another subsequent reply without the
 		 * calling '_wait()' in between. This is needed when a server
 		 * answers calls out of order.

repos/base/include/base/lock_guard.h

@@ -2,13 +2,6 @@
  * \brief  Lock guard
  * \author Norman Feske
  * \date   2006-07-26
- *
- * A lock guard is instantiated as a local variable.
- * When a lock guard is constructed, it acquires the lock that
- * is specified as constructor argument. When the control
- * flow leaves the scope of the lock guard variable via
- * a return statement or an exception, the lock guard's
- * destructor gets called, freeing the lock.
  */
 
 /*
@@ -28,6 +21,12 @@ namespace Genode { template <typename> class Lock_guard; }
  * Lock guard template
  *
  * \param LT  lock type
+ *
+ * A lock guard is instantiated as a local variable. When a lock guard is
+ * constructed, it acquires the lock that is specified as constructor argument.
+ * When the control flow leaves the scope of the lock-guard variable via a
+ * return statement or an exception, the lock guard's destructor gets called,
+ * freeing the lock.
  */
 template <typename LT>
 class Genode::Lock_guard

repos/base/include/base/native_capability.h

@@ -38,8 +38,8 @@ namespace Genode { template <typename> class Native_capability_tpl; }
  *
  * The 'Dst' type is the platform-specific destination type (e.g., the ID
  * of the destination thread targeted by the capability). The 'valid'
- * function returns true if the specified destination is valid. The
+ * method returns true if the specified destination is valid. The
- * 'invalid' function produces an invalid destination.
+ * 'invalid' method produces an invalid destination.
  */
 template <typename POLICY>
 class Genode::Native_capability_tpl

repos/base/include/base/object_pool.h

@@ -73,10 +73,11 @@ class Genode::Object_pool
 				friend class Object_pool;
 				friend class Avl_tree<Entry>;
 
-				/**
+				/*
-				 * Support functions for atomic lookup and lock
+				 * Support methods for atomic lookup and lock functionality of
-				 * functionality of class Object_pool.
+				 * class Object_pool.
 				 */
+
 				void lock()   { _entry_lock.lock(); };
 				void unlock() { _entry_lock.unlock(); };
 

repos/base/include/base/pager.h

@@ -149,7 +149,7 @@ class Genode::Pager_activation_base: public Thread_base
 		/**
 		 * Set entry point, which the activation serves
 		 *
-		 * This function is only called by the 'Pager_entrypoint'
+		 * This method is only called by the 'Pager_entrypoint'
 		 * constructor.
 		 */
 		void ep(Pager_entrypoint *ep) { _ep = ep; }
@@ -162,7 +162,7 @@ class Genode::Pager_activation_base: public Thread_base
 		/**
 		 * Return capability to this activation
 		 *
-		 * This function should only be called from 'Pager_entrypoint'
+		 * This method should only be called from 'Pager_entrypoint'
 		 */
 		Native_capability cap()
 		{

repos/base/include/base/printf.h

@@ -1,5 +1,5 @@
 /*
- * \brief  Interface of the printf backend
+ * \brief  Interface of the printf back end
  * \author Norman Feske
  * \date   2006-04-08
  */
@@ -19,9 +19,10 @@
 namespace Genode {
 
 	/**
-	 * For your convenience...
+	 * Output format string to LOG session
 	 */
 	void  printf(const char *format, ...) __attribute__((format(printf, 1, 2)));
+
 	void vprintf(const char *format, va_list) __attribute__((format(printf, 1, 0)));
 }
 

repos/base/include/base/rpc.h

@@ -18,7 +18,7 @@
 
 
 /**
- * Macro for declaring a RPC function
+ * Macro for declaring an RPC function
  *
  * \param rpc_name   type name representing the RPC function
  * \param ret_type   RPC return type

repos/base/include/base/rpc_args.h

@@ -114,7 +114,7 @@ class Genode::Rpc_in_buffer : public Rpc_in_buffer_base
 		 *
 		 * \return  pointer to null-terminated string
 		 *
-		 * The function returns an empty string if the buffer does not hold
+		 * The method returns an empty string if the buffer does not hold
 		 * a valid null-terminated string. To distinguish a buffer holding
 		 * an invalid string from a buffer holding a valid empty string,
 		 * the function 'is_valid_string' can be used.

repos/base/include/base/rpc_client.h

@@ -19,24 +19,7 @@
 
 namespace Genode {
 
-	/**
+	template <typename> struct Rpc_client;
-	 * RPC client
-	 *
-	 * This class template is the base class of the client-side implementation
-	 * of the specified 'RPC_INTERFACE'. Usually, it inherits the pure virtual
-	 * functions declared in 'RPC_INTERFACE' and has the built-in facility to
-	 * perform RPC calls to this particular interface. Hence, the client-side
-	 * implementation of each pure virtual interface function comes down to a
-	 * simple wrapper in the line of 'return call<Rpc_function>(arguments...)'.
-	 */
-	template <typename RPC_INTERFACE>
-	struct Rpc_client : Capability<RPC_INTERFACE>, RPC_INTERFACE
-	{
-		typedef RPC_INTERFACE Rpc_interface;
-
-		Rpc_client(Capability<RPC_INTERFACE> const &cap)
-		: Capability<RPC_INTERFACE>(cap) { }
-	};
 
 	/**
 	 * Count capabilities of a RPC_FUNCTION which are out parameters.
@@ -68,9 +51,9 @@ namespace Genode {
 		enum { Value = Rpc_caps_out<typename RPC_FUNCTION::Server_args>::Value +
 		               Cap_return  <typename RPC_FUNCTION::Ret_type>::Value}; };
 
-	/*********************************************************
+	/***************************************************
 	 ** Implementation of 'Capability:call' functions **
-	 *********************************************************/
+	 ***************************************************/
 
 	template <typename RPC_INTERFACE>
 	template <typename ATL>
@@ -171,4 +154,25 @@ namespace Genode {
 	}
 }
 
+
+/**
+ * RPC client
+ *
+ * This class template is the base class of the client-side implementation
+ * of the specified 'RPC_INTERFACE'. Usually, it inherits the pure virtual
+ * functions declared in 'RPC_INTERFACE' and has the built-in facility to
+ * perform RPC calls to this particular interface. Hence, the client-side
+ * implementation of each pure virtual interface function comes down to a
+ * simple wrapper in the line of 'return call<Rpc_function>(arguments...)'.
+ */
+template <typename RPC_INTERFACE>
+struct Genode::Rpc_client : Capability<RPC_INTERFACE>, RPC_INTERFACE
+{
+	typedef RPC_INTERFACE Rpc_interface;
+
+	Rpc_client(Capability<RPC_INTERFACE> const &cap)
+	: Capability<RPC_INTERFACE>(cap) { }
+};
+
+
 #endif /* _INCLUDE__BASE__RPC_CLIENT_H_ */

repos/base/include/base/rpc_server.h

@@ -42,11 +42,11 @@ namespace Genode {
  * server functions according to the RPC declarations in 'RPC_INTERFACE'.
  *
  * If using the default argument for 'SERVER', the 'RPC_INTERFACE' is expected
- * to contain the abstract interface for all RPC functions. So virtual functions
+ * to contain the abstract interface for all RPC functions. So virtual methods
  * must be declared in 'RPC_INTERFACE'. In contrast, by explicitly specifying
- * the 'SERVER' argument, the server-side dispatching performs direct function
+ * the 'SERVER' argument, the server-side dispatching performs direct
- * calls to the respective member functions of the 'SERVER' class and thereby
+ * calls to the respective methods of the 'SERVER' class and thereby
- * omits virtual functions calls.
+ * omits virtual method calls.
  */
 template <typename RPC_INTERFACE, typename SERVER = RPC_INTERFACE>
 class Genode::Rpc_dispatcher : public RPC_INTERFACE
@@ -232,7 +232,7 @@ struct Genode::Rpc_object : Rpc_object_base, Rpc_dispatcher<RPC_INTERFACE, SERVE
  * activation-using server can ensure that it gets initialized completely
  * before the first capability invocations come in. Once the server is
  * ready, it must enable the entrypoint explicitly by calling the
- * 'activate()' function. The 'start_on_construction' argument is a
+ * 'activate()' method. The 'start_on_construction' argument is a
  * shortcut for the common case where the server's capability is handed
  * over to other parties _after_ the server is completely initialized.
  */
@@ -253,7 +253,7 @@ class Genode::Rpc_entrypoint : Thread_base, public Object_pool<Rpc_object_base>
 		/**
 		 * Hook to let low-level thread init code access private members
 		 *
-		 * This function is only used on NOVA.
+		 * This method is only used on NOVA.
 		 */
 		static void _activation_entry();
 
@@ -285,27 +285,37 @@ class Genode::Rpc_entrypoint : Thread_base, public Object_pool<Rpc_object_base>
 		Capability<Exit> _exit_cap;
 
 		/**
-		 * Back-end function to associate RPC object with the entry point
+		 * Back end used to associate RPC object with the entry point
+		 *
+		 * \noapi
 		 */
 		Untyped_capability _manage(Rpc_object_base *obj);
 
 		/**
-		 * Back-end function to Dissolve RPC object from entry point
+		 * Back end used to Dissolve RPC object from entry point
+		 *
+		 * \noapi
 		 */
 		void _dissolve(Rpc_object_base *obj);
 
 		/**
 		 * Force activation to cancel dispatching the specified server object
+		 *
+		 * \noapi
 		 */
 		void _leave_server_object(Rpc_object_base *obj);
 
 		/**
 		 * Wait until the entrypoint activation is initialized
+		 *
+		 * \noapi
 		 */
 		void _block_until_cap_valid();
 
 		/**
 		 * Thread interface
+		 *
+		 * \noapi
 		 */
 		void entry();
 
@@ -354,10 +364,12 @@ class Genode::Rpc_entrypoint : Thread_base, public Object_pool<Rpc_object_base>
 		/**
 		 * Request reply capability for current call
 		 *
-		 * Note: This is a temporary API function, which is going to be
+		 * \noapi
-		 * removed. Please do not use this function.
 		 *
-		 * Typically, a capability obtained via this function is used as
+		 * Note: This is a temporary API method, which is going to be
+		 * removed. Please do not use this method.
+		 *
+		 * Typically, a capability obtained via this method is used as
 		 * argument of 'intermediate_reply'.
 		 */
 		Untyped_capability reply_dst();
@@ -365,24 +377,28 @@ class Genode::Rpc_entrypoint : Thread_base, public Object_pool<Rpc_object_base>
 		/**
 		 * Prevent reply of current request
 		 *
-		 * Note: This is a temporary API function, which is going to be
+		 * \noapi
-		 * removed. Please do not use this function.
 		 *
-		 * This function can be used to keep the calling client blocked
+		 * Note: This is a temporary API method, which is going to be
+		 * removed. Please do not use this method.
+		 *
+		 * This method can be used to keep the calling client blocked
 		 * after the server has finished the processing of the client's
 		 * request. At a later time, the server may chose to unblock the
-		 * client via the 'intermedate_reply' function.
+		 * client via the 'intermedate_reply' method.
 		 */
 		void omit_reply();
 
 		/**
 		 * Send a reply out of the normal call-reply order
 		 *
-		 * Note: This is a temporary API function, which is going to be
+		 * \noapi
-		 * removed. Please do not use this function.
 		 *
-		 * In combination with the 'reply_dst' accessor functions, this
+		 * Note: This is a temporary API method, which is going to be
-		 * function can be used to implement services that dispatch client
+		 * removed. Please do not use this method.
+		 *
+		 * In combination with the 'reply_dst' accessor method, this
+		 * method can be used to implement services that dispatch client
 		 * requests out of order. In such cases, the server activation may
 		 * send reply messages to multiple blocking clients before
 		 * answering the original call.
@@ -391,6 +407,10 @@ class Genode::Rpc_entrypoint : Thread_base, public Object_pool<Rpc_object_base>
 
 		/**
 		 * Return true if the caller corresponds to the entrypoint called
+		 *
+		 * \noapi
+		 *
+		 * This method is solely needed on Linux.
 		 */
 		bool is_myself() const;
 };

repos/base/include/base/semaphore.h

@@ -53,6 +53,12 @@ class Genode::Semaphore
 			try { _meta_lock.lock(); } catch (...) { }
 		}
 
+		/**
+		 * Increment semphore counter
+		 *
+		 * This method may wake up another thread that currently blocks on
+		 * a 'down' call at the same semaphore.
+		 */
 		void up()
 		{
 			Lock::Guard lock_guard(_meta_lock);
@@ -69,6 +75,9 @@ class Genode::Semaphore
 				element->wake_up();
 		}
 
+		/**
+		 * Decrement semaphore counter, block if the counter reaches zero
+		 */
 		void down()
 		{
 			_meta_lock.lock();

repos/base/include/base/service.h

@@ -370,9 +370,9 @@ class Genode::Service_registry
 		/**
 		 * Wait for service
 		 *
-		 * This function is called by the clients's thread
+		 * This method is called by the clients's thread when requesting a
-		 * when requesting a session creation. It blocks
+		 * session creation. It blocks if the requested service is not
-		 * if the requested service is not available.
+		 * available.
 		 *
 		 * \return  service structure that matches the request or
 		 *          0 if the waiting was canceled.
@@ -422,7 +422,7 @@ class Genode::Service_registry
 		/**
 		 * Register service
 		 *
-		 * This function is called by the server's thread.
+		 * This method is called by the server's thread.
 		 */
 		void insert(Service *service)
 		{

repos/base/include/base/signal.h

@@ -91,7 +91,7 @@ class Genode::Signal
 		 */
 		Signal(Data data);
 
-	    friend class Kernel::Signal_receiver;
+		friend class Kernel::Signal_receiver;
 		friend class Signal_receiver;
 		friend class Signal_context;
 
@@ -101,7 +101,12 @@ class Genode::Signal
 	public:
 
 		Signal(Signal const &other);
-		Signal &operator=(Signal const &other);
+
+		/**
+		 * \noapi
+		 */
+		Signal &operator = (Signal const &other);
+
 		~Signal();
 
 		Signal_context *context()       { return _data.context; }
@@ -184,9 +189,9 @@ class Genode::Signal_receiver : Noncopyable
 		/**
 		 * Helper to dissolve given context
 		 *
-		 * This function prevents duplicated code in '~Signal_receiver'
+		 * This method prevents duplicated code in '~Signal_receiver'
 		 * and 'dissolve'. Note that '_contexts_lock' must be held when
-		 * calling this function.
+		 * calling this method.
 		 */
 		void _unsynchronized_dissolve(Signal_context *context);
 
@@ -246,13 +251,17 @@ class Genode::Signal_receiver : Noncopyable
 
 		/**
 		 * Locally submit signal to the receiver
+		 *
+		 * \noapi
 		 */
 		void local_submit(Signal::Data signal);
 
 		/**
 		 * Framework-internal signal-dispatcher
 		 *
-		 * This function is called from the thread that monitors the signal
+		 * \noapi
+		 *
+		 * This method is called from the thread that monitors the signal
 		 * source associated with the process. It must not be used for other
 		 * purposes.
 		 */
@@ -265,7 +274,7 @@ class Genode::Signal_receiver : Noncopyable
  *
  * A signal context is a destination for signals. One receiver can listen
  * to multple contexts. If a signal arrives, the context is provided with the
- * signel. This enables the receiver to distinguish different signal sources
+ * signal. This enables the receiver to distinguish different signal sources
  * and dispatch incoming signals context-specific.
  */
 class Genode::Signal_context
@@ -286,7 +295,7 @@ class Genode::Signal_context
 		 * Receiver to which the context is associated with
 		 *
 		 * This member is initialized by the receiver when associating
-		 * the context with the receiver via the 'cap' function.
+		 * the context with the receiver via the 'cap' method.
 		 */
 		Signal_receiver *_receiver;
 
@@ -299,7 +308,7 @@ class Genode::Signal_context
 
 		/**
 		 * Capability assigned to this context after being assocated with
-		 * a 'Signal_receiver' via the 'manage' function. We store this
+		 * a 'Signal_receiver' via the 'manage' method. We store this
 		 * capability in the 'Signal_context' for the mere reason to
 		 * properly destruct the context (see '_unsynchronized_dissolve').
 		 */
@@ -330,6 +339,8 @@ class Genode::Signal_context
 		/**
 		 * Local signal submission (DEPRECATED)
 		 *
+		 * \noapi
+		 *
 		 * Trigger local signal submission (within the same address space), the
 		 * context has to be bound to a sginal receiver beforehand.
 		 *
@@ -339,7 +350,7 @@ class Genode::Signal_context
 
 		/*
 		 * Signal contexts are never invoked but only used as arguments for
-		 * 'Signal_session' functions. Hence, there exists a capability
+		 * 'Signal_session' methods. Hence, there exists a capability
 		 * type for it but no real RPC interface.
 		 */
 		GENODE_RPC_INTERFACE();
@@ -356,13 +367,13 @@ struct Genode::Signal_dispatcher_base : Signal_context
 
 
 /**
- * Adapter for directing signals to member functions
+ * Adapter for directing signals to object methods
  *
- * This utility associates member functions with signals. It is intended to
+ * This utility associates object methods with signals. It is intended to
  * be used as a member variable of the class that handles incoming signals
  * of a certain type. The constructor takes a pointer-to-member to the
- * signal handling function as argument. If a signal is received at the
+ * signal handling method as argument. If a signal is received at the
- * common signal reception code, this function will be invoked by calling
+ * common signal reception code, this method will be invoked by calling
  * 'Signal_dispatcher_base::dispatch'.
  *
  * \param T  type of signal-handling class
@@ -384,7 +395,7 @@ class Genode::Signal_dispatcher : public Signal_dispatcher_base,
 		 *
 		 * \param sig_rec     signal receiver to associate the signal
 		 *                    handler with
-		 * \param obj,member  object and member function to call when
+		 * \param obj,member  object and method to call when
 		 *                    the signal occurs
 		 */
 		Signal_dispatcher(Signal_receiver &sig_rec,

repos/base/include/base/slab.h

@@ -59,11 +59,13 @@ class Genode::Slab_block
 		 */
 
 		/**
-		 * Accessor functions to allocation state
+		 * Return the allocation state of a slab entry
-		 *
-		 * \param idx  index of slab entry
 		 */
 		inline bool state(int idx) { return _data[idx]; }
+
+		/**
+		 * Set the allocation state of a slab entry
+		 */
 		inline void state(int idx, bool state) { _data[idx] = state; }
 
 		/**
@@ -205,16 +207,22 @@ class Genode::Slab : public Allocator
 
 		/**
 		 * Debug function for dumping the current slab block list
+		 *
+		 * \noapi
 		 */
 		void dump_sb_list();
 
 		/**
 		 * Remove block from slab block list
+		 *
+		 * \noapi
 		 */
 		void remove_sb(Slab_block *sb);
 
 		/**
 		 * Insert block into slab block list
+		 *
+		 * \noapi
 		 */
 		void insert_sb(Slab_block *sb, Slab_block *at = 0);
 
@@ -235,8 +243,16 @@ class Genode::Slab : public Allocator
 
 		/**
 		 * Define/request backing-store allocator
+		 *
+		 * \noapi
 		 */
 		void backing_store(Allocator *bs) { _backing_store = bs; }
+
+		/**
+		 * Request backing-store allocator
+		 *
+		 * \noapi
+		 */
 		Allocator *backing_store() { return _backing_store; }
 
 		/*************************

repos/base/include/base/snprintf.h

@@ -24,9 +24,13 @@ namespace Genode {
 	/**
 	 * Print format string into character buffer
 	 *
+	 * \param dst      destination buffer
+	 * \param dst_len  size of 'dst' in bytes
+	 * \param format   format string followed by the list of arguments
+	 *
 	 * \return  number of characters written to destination buffer
 	 */
-	inline int snprintf(char *, size_t, const char *, ...)
+	inline int snprintf(char *dst, size_t dst_size, const char *format, ...)
 	           __attribute__((format(printf, 3, 4)));
 }
 
@@ -45,7 +49,7 @@ class Genode::String_console : public Console
 		 * Constructor
 		 *
 		 * \param dst      destination character buffer
-		 * \param dst_len  size of dst
+		 * \param dst_len  size of 'dst'
 		 */
 		String_console(char *dst, size_t dst_len)
 		: _dst(dst), _dst_len(dst_len), _w_offset(0)

repos/base/include/base/stdint.h

@@ -1,5 +1,5 @@
 /*
- * \brief  Genode-specific integer types
+ * \brief  Integer types
  * \author Christian Helmuth
  * \date   2006-05-10
  */

repos/base/include/base/sync_allocator.h

@@ -165,7 +165,7 @@ class Genode::Synchronized_range_allocator : public Range_allocator
 		 * methods in addition to the Range_allocator interface.
 		 *
 		 * NOTE: Synchronize accesses to the raw allocator by facilitating
-		 * the lock() member function.
+		 * the lock() method.
 		 */
 		ALLOCATOR_IMPL *raw() { return &_alloc; }
 

repos/base/include/base/thread.h

@@ -78,7 +78,7 @@ namespace Genode {
  * Concurrent control flow
  *
  * A 'Thread_base' object corresponds to a physical thread. The execution
- * starts at the 'entry()' function as soon as 'start()' is called.
+ * starts at the 'entry()' method as soon as 'start()' is called.
  */
 class Genode::Thread_base
 {
@@ -260,7 +260,7 @@ class Genode::Thread_base
 		 *
 		 * On some platforms, each new thread has to perform a startup
 		 * protocol, e.g., waiting for a message from the kernel. This hook
-		 * function allows for the implementation of such protocols.
+		 * method allows for the implementation of such protocols.
 		 */
 		void _thread_bootstrap();
 
@@ -323,7 +323,7 @@ class Genode::Thread_base
 		/**
 		 * Return 'Trace::Logger' instance of calling thread
 		 *
-		 * This function is used by the tracing framework internally.
+		 * This method is used by the tracing framework internally.
 		 */
 		static Trace::Logger *_logger();
 
@@ -354,7 +354,7 @@ class Genode::Thread_base
 		 * Constructor
 		 *
 		 * \param quota       CPU quota that shall be granted to the thread
-		 * \param name        thread name for debugging
+		 * \param name        thread name for DEBUGging
 		 * \param stack_size  stack size
 		 *
 		 * \throw Stack_too_large
@@ -365,7 +365,6 @@ class Genode::Thread_base
 		 * of the process environment. A small portion of the stack size is
 		 * internally used by the framework for storing thread-context
 		 * information such as the thread's name ('Context').
-		 *
 		 */
 		Thread_base(size_t quota, const char *name, size_t stack_size)
 		:
@@ -400,14 +399,14 @@ class Genode::Thread_base
 		virtual ~Thread_base();
 
 		/**
-		 * Entry function of the thread
+		 * Entry method of the thread
 		 */
 		virtual void entry() = 0;
 
 		/**
 		 * Start execution of the thread
 		 *
-		 * This function is virtual to enable the customization of threads
+		 * This method is virtual to enable the customization of threads
 		 * used as server activation.
 		 */
 		virtual void start();
@@ -450,7 +449,9 @@ class Genode::Thread_base
 		void cancel_blocking();
 
 		/**
-		 * Only to be called from platform-specific code
+		 * Return thread ID
+		 *
+		 * \noapi  Only to be called from platform-specific code
 		 */
 		Native_thread & tid() { return _tid; }
 
@@ -471,8 +472,7 @@ class Genode::Thread_base
 		/**
 		 * Return 'Thread_base' object corresponding to the calling thread
 		 *
-		 * \return  pointer to 'Thread_base' object, or
+		 * \return  pointer to caller's 'Thread_base' object
-		 *          0 if the calling thread is the main thread
 		 */
 		static Thread_base *myself();
 
@@ -489,14 +489,15 @@ class Genode::Thread_base
 		/**
 		 * Return user-level thread control block
 		 *
-		 * Note that it is safe to call this function on the result of the
+		 * Note that it is safe to call this method on the result of the
-		 * 'myself' function. It handles the special case of 'myself' being
+		 * 'myself' class function. It handles the special case of 'myself'
-		 * 0 when called by the main thread.
+		 * being 0 when called by the main thread during the component
+		 * initialization phase.
 		 */
 		Native_utcb *utcb();
 
 		/**
-		 * Block until the thread leaves the 'entry' function
+		 * Block until the thread leaves the 'entry' method
 		 *
 		 * Join must not be called more than once. Subsequent calls have
 		 * undefined behaviour.

repos/base/include/base/weak_ptr.h

@@ -2,40 +2,6 @@
  * \brief  Utilities for object life-time management
  * \author Norman Feske
  * \date   2013-03-09
- *
- * This header provides utilities for avoiding dangling pointers. Such a
- * situation happens when an object disappears while pointers to the object
- * are still in use. One way to solve this problem is to explicitly notify the
- * holders of those pointers about the disappearance of the object. But this
- * would require the object to keep references to those pointer holder, which,
- * in turn, might disappear as well. Consequently, this approach tends to
- * become a complex solution, which is prone to deadlocks or race conditions
- * when multiple threads are involved.
- *
- * The utilities provided herein implement a more elegant pattern called
- * "weak pointers" to deal with such situations. An object that might
- * disappear at any time is represented by the 'Weak_object' class
- * template. It keeps track of a list of so-called weak pointers pointing
- * to the object. A weak pointer, in turn, holds privately the pointer to the
- * object alongside a validity flag. It cannot be used to dereference the
- * object. For accessing the actual object, a locked pointer must be created
- * from a weak pointer. If this creation succeeds, the object is guaranteed to
- * be locked (not destructed) until the locked pointer gets destroyed. If the
- * object no longer exists, the locked pointer will be invalid. This condition
- * can (and should) be detected via the 'Locked_ptr::is_valid()' function prior
- * dereferencing the pointer.
- *
- * In the event a weak object gets destructed, all weak pointers that point
- * to the object are automatically invalidated. So a subsequent conversion into
- * a locked pointer will yield an invalid pointer, which can be detected (in
- * contrast to a dangling pointer).
- *
- * To use this mechanism, the destruction of a weak object must be
- * deferred until no locked pointer points to the object anymore. This is
- * done by calling the function 'Weak_object::lock_for_destruction()'
- * at the beginning of the destructor of the to-be-destructed object.
- * When this function returns, all weak pointers to the object will have been
- * invalidated. So it is save to destruct and free the object.
  */
 
 /*
@@ -62,6 +28,12 @@ namespace Genode {
 }
 
 
+/**
+ * Type-agnostic base class of a weak pointer
+ *
+ * This class implements the mechanics of the the 'Weak_ptr' class template.
+ * It is not used directly.
+ */
 class Genode::Weak_ptr_base : public Genode::List<Weak_ptr_base>::Element
 {
 	private:
@@ -79,6 +51,11 @@ class Genode::Weak_ptr_base : public Genode::List<Weak_ptr_base>::Element
 
 	protected:
 
+		/**
+		 * Return pointer to object if it exists, or 0 if object vanished
+		 *
+		 * \noapi
+		 */
 		Weak_object_base *obj() const { return _valid ? _obj: 0; }
 
 		explicit inline Weak_ptr_base(Weak_object_base *obj);
@@ -104,11 +81,16 @@ class Genode::Weak_ptr_base : public Genode::List<Weak_ptr_base>::Element
 
 		/**
 		 * Inspection hook for unit test
+		 *
+		 * \noapi
 		 */
 		void debug_info() const;
 };
 
 
+/**
+ * Type-agnostic base class of a weak object
+ */
 class Genode::Weak_object_base
 {
 	private:
@@ -130,10 +112,17 @@ class Genode::Weak_object_base
 
 	protected:
 
+		/**
+		 * Destructor
+		 *
+		 * \noapi
+		 */
 		inline ~Weak_object_base();
 
 		/**
 		 * To be called from 'Weak_object<T>' only
+		 *
+		 * \noapi
 		 */
 		template <typename T>
 		Weak_ptr<T> _weak_ptr();
@@ -141,13 +130,17 @@ class Genode::Weak_object_base
 	public:
 
 		/**
-		 * Function to be called by the destructor of a weak object to
+		 * Mark object as safe to be destructed
+		 *
+		 * This method must be called by the destructor of a weak object to
 		 * defer the destruction until no 'Locked_ptr' is held to the object.
 		 */
 		void lock_for_destruction() { _destruct_lock.lock(); }
 
 		/**
 		 * Inspection hook for unit test
+		 *
+		 * \noapi
 		 */
 		void debug_info() const;
 };
@@ -159,11 +152,33 @@ class Genode::Locked_ptr_base
 
 		Weak_object_base *curr;
 
+		/**
+		 * Constructor
+		 *
+		 * \noapi
+		 */
 		inline Locked_ptr_base(Weak_ptr_base &weak_ptr);
+
+		/**
+		 * Destructor
+		 *
+		 * \noapi
+		 */
 		inline ~Locked_ptr_base();
 };
 
 
+/**
+ * Weak pointer to a given type
+ *
+ * A weak pointer can be obtained from a weak object (an object that inherits
+ * the 'Weak_object' class template) and safely survives the lifetime of the
+ * associated weak object. If the weak object disappears, all
+ * weak pointers referring to the object are automatically invalidated.
+ * To avoid race conditions between the destruction and use of a weak object,
+ * a weak pointer cannot be de-reference directly. To access the object, a
+ * weak pointer must be turned into a locked pointer ('Locked_ptr').
+ */
 template <typename T>
 struct Genode::Weak_ptr : Genode::Weak_ptr_base
 {
@@ -187,13 +202,38 @@ struct Genode::Weak_ptr : Genode::Weak_ptr_base
 };
 
 
+/**
+ * Weak object
+ *
+ * This class template must be inherited in order to equip an object with
+ * the weak-pointer mechanism.
+ *
+ * \param T  type of the derived class
+ */
 template <typename T>
 struct Genode::Weak_object : Genode::Weak_object_base
 {
+	/**
+	 * Obtain a weak pointer referring to the weak object
+	 */
 	Weak_ptr<T> weak_ptr() { return _weak_ptr<T>(); }
 };
 
 
+/**
+ * Locked pointer
+ *
+ * A locked pointer is constructed from a weak pointer. After construction,
+ * its validity can (and should) be checked by calling the 'is_valid'
+ * method. If the locked pointer is valid, the pointed-to object is known to
+ * be locked until the locked pointer is destroyed. During this time, the
+ * locked pointer can safely be de-referenced.
+ *
+ * The typical pattern of using a locked pointer is to declare it as a
+ * local variable. Once the execution leaves the scope of the variable, the
+ * locked pointer is destructed, which unlocks the pointed-to weak object.
+ * It effectively serves as a lock guard.
+ */
 template <typename T>
 struct Genode::Locked_ptr : Genode::Locked_ptr_base
 {
@@ -203,6 +243,12 @@ struct Genode::Locked_ptr : Genode::Locked_ptr_base
 
 	T &operator * () { return *static_cast<T *>(curr); }
 
+	/**
+	 * Returns true if the locked pointer is valid
+	 *
+	 * Only if valid, the locked pointer can be de-referenced. Otherwise,
+	 * the attempt will result in a null-pointer access.
+	 */
 	bool is_valid() const { return curr != 0; }
 };
 

repos/base/include/cpu_session/cpu_session.h

@@ -103,7 +103,7 @@ struct Genode::Cpu_session : Session
 	/**
 	 * Pause the specified thread
 	 *
-	 * After calling this function, the execution of the thread can be
+	 * After calling this method, the execution of the thread can be
 	 * continued by calling 'resume'.
 	 */
 	virtual void pause(Thread_capability thread) = 0;
@@ -158,7 +158,7 @@ struct Genode::Cpu_session : Session
 	/**
 	 * Enable/disable single stepping for specified thread.
 	 *
-	 * Since this functions is currently supported by a small number of
+	 * Since this method is currently supported by a small number of
 	 * platforms, we provide a default implementation
 	 *
 	 * \param thread  thread to set into single step mode
@@ -169,7 +169,7 @@ struct Genode::Cpu_session : Session
 	/**
 	 * Return affinity space of CPU nodes available to the CPU session
 	 *
-	 * The dimension of the affinity space as returned by this function
+	 * The dimension of the affinity space as returned by this method
 	 * represent the physical CPUs that are available.
 	 */
 	virtual Affinity::Space affinity_space() const = 0;
@@ -335,7 +335,7 @@ struct Genode::Cpu_session : Session
 	/*
 	 * 'GENODE_RPC_INTERFACE' declaration done manually
 	 *
-	 * The number of RPC function of this interface exceeds the maximum
+	 * The number of RPC functions of this interface exceeds the maximum
 	 * number of elements supported by 'Meta::Type_list'. Therefore, we
 	 * construct the type list by hand using nested type tuples instead
 	 * of employing the convenience macro 'GENODE_RPC_INTERFACE'.

repos/base/include/io_port_session/io_port_session.h

@@ -7,7 +7,7 @@
  * variable-sized accesses (i.e., 8, 16, 32 bit) at arbitrary addresses are
  * allowed - currently, alignment is not enforced. Core enforces that access is
  * limited to the session-defined range while the user provides physical I/O port
- * addresses as function parameters.
+ * addresses as arguments.
  *
  * The design is founded on experiences while programming PCI configuration
  * space which needs two 32-bit port registers. Each byte, word and dword in

repos/base/include/parent/parent.h

@@ -90,7 +90,7 @@ class Genode::Parent
 		 * The type of the specified 'service_root' capability match with
 		 * an interface that provides a 'Session_type' type (i.e., a
 		 * 'Typed_root' interface). This 'Session_type' is expected to
-		 * host a static function called 'service_name' returning the
+		 * host a class function called 'service_name' returning the
 		 * name of the provided interface as null-terminated string.
 		 */
 		template <typename ROOT_INTERFACE>
@@ -123,7 +123,7 @@ class Genode::Parent
 		 *
 		 * \return                 untyped capability to new session
 		 *
-		 * The use of this function is discouraged. Please use the type safe
+		 * The use of this method is discouraged. Please use the type safe
 		 * 'session()' template instead.
 		 */
 		virtual Session_capability session(Service_name const &service_name,
@@ -162,7 +162,7 @@ class Genode::Parent
 		 * \throw Quota_exceeded  quota could not be transferred
 		 *
 		 * The 'args' argument has the same principle format as the 'args'
-		 * argument of the 'session' function.
+		 * argument of the 'session' operation.
 		 * The error case indicates that there is not enough unused quota on
 		 * the source side.
 		 */
@@ -187,7 +187,7 @@ class Genode::Parent
 		/**
 		 * Request additional resources
 		 *
-		 * By invoking this function, a process is able to inform its
+		 * By invoking this method, a process is able to inform its
 		 * parent about the need for additional resources. The argument
 		 * string contains a resource description in the same format as
 		 * used for session-construction arguments. In particular, for
@@ -212,7 +212,7 @@ class Genode::Parent
 		/**
 		 * Obtain information about the amount of resources to free
 		 *
-		 * The amount of resources returned by this function is the
+		 * The amount of resources returned by this method is the
 		 * goal set by the parent. It is not commanded but merely meant
 		 * as a friendly beg to cooperate. The process is not obligated
 		 * to comply. If the process decides to take action to free

repos/base/include/ram_session/client.h

@@ -1,5 +1,5 @@
 /*
- * \brief  Client-side ram session interface
+ * \brief  Client-side RAM session interface
  * \author Norman Feske
  * \date   2006-05-31
  */

repos/base/include/ram_session/ram_session.h

@@ -34,6 +34,9 @@ namespace Genode {
 struct Genode::Ram_dataspace : Dataspace { };
 
 
+/**
+ * RAM session interface
+ */
 struct Genode::Ram_session : Session
 {
 	static const char *service_name() { return "RAM"; }

repos/base/include/rom_session/rom_session.h

@@ -46,11 +46,11 @@ struct Genode::Rom_session : Session
 	 *
 	 * The capability may be invalid.
 	 *
-	 * Consecutive calls of this functions are not guaranteed to return the
+	 * Consecutive calls of this method are not guaranteed to return the
 	 * same dataspace as dynamic ROM sessions may update the ROM data
-	 * during the lifetime of the session. When calling the function, the
+	 * during the lifetime of the session. When calling the method, the
 	 * server may destroy the old dataspace and replace it with a new one
-	 * containing the updated data. Hence, prior calling this function, the
+	 * containing the updated data. Hence, prior calling this method, the
 	 * client should make sure to detach the previously requested dataspace
 	 * from its local address space.
 	 */
@@ -59,7 +59,7 @@ struct Genode::Rom_session : Session
 	/**
 	 * Update ROM dataspace content
 	 *
-	 * This function is an optimization for use cases where ROM dataspaces
+	 * This method is an optimization for use cases where ROM dataspaces
 	 * are updated at a high rate. In such cases, requesting a new
 	 * dataspace for each update induces a large overhead because
 	 * memory mappings must be revoked and updated (e.g., handling the
@@ -67,12 +67,12 @@ struct Genode::Rom_session : Session
 	 * fits in the existing dataspace, those costly operations can be
 	 * omitted.
 	 *
-	 * When this function is called, the server may replace the dataspace
+	 * When this method is called, the server may replace the dataspace
 	 * content with new data.
 	 *
 	 * \return true if the existing dataspace contains up-to-date content,
 	 *         or false if a new dataspace must be requested via the
-	 *         'dataspace' function
+	 *         'dataspace' method
 	 */
 	virtual bool update() { return false; }
 
@@ -85,7 +85,7 @@ struct Genode::Rom_session : Session
 	 * where this data is generated rather than originating from a static
 	 * file, for example to update a program's configuration at runtime.
 	 *
-	 * By installing a signal handler using the 'sigh()' function, the
+	 * By installing a signal handler using the 'sigh()' method, the
 	 * client will receive a notification each time the data changes at the
 	 * server. From the client's perspective, the original data contained
 	 * in the currently used dataspace remains unchanged until the client

repos/base/include/root/component.h

@@ -78,7 +78,7 @@ struct Genode::Multiple_clients
  * creation to only one instance at a time (using the 'Single_session'
  * policy) or multiple instances (using the 'Multiple_sessions' policy).
  *
- * The 'POLICY' class must provide the following two functions:
+ * The 'POLICY' class must provide the following two methods:
  *
  * :'aquire(const char *args)': is called with the session arguments
  *   at creation time of each new session. It can therefore implement
@@ -123,7 +123,7 @@ class Genode::Root_component : public Rpc_object<Typed_root<SESSION_TYPE> >,
 		 * of its 'new' operator and must implement the session
 		 * creation at a place, where the required knowledge exist.
 		 *
-		 * In the implementation of this function, the heap, provided
+		 * In the implementation of this method, the heap, provided
 		 * by 'Root_component' must be used for allocating the session
 		 * object.
 		 *
@@ -151,16 +151,16 @@ class Genode::Root_component : public Rpc_object<Typed_root<SESSION_TYPE> >,
 		 * Inform session about a quota upgrade
 		 *
 		 * Once a session is created, its client can successively extend
-		 * its quota donation via the 'Parent::transfer_quota' function.
+		 * its quota donation via the 'Parent::transfer_quota' operation.
 		 * This will result in the invokation of 'Root::upgrade' at the
 		 * root interface the session was created with. The root interface,
 		 * in turn, informs the session about the new resources via the
-		 * '_upgrade_session' function. The default implementation is
+		 * '_upgrade_session' method. The default implementation is
 		 * suited for sessions that use a static amount of resources
 		 * accounted for at session-creation time. For such sessions, an
 		 * upgrade is not useful. However, sessions that dynamically
 		 * allocate resources on behalf of its client, should respond to
-		 * quota upgrades by implementing this function.
+		 * quota upgrades by implementing this method.
 		 *
 		 * \param session  session to upgrade
 		 * \param args     description of additional resources in the
@@ -174,8 +174,12 @@ class Genode::Root_component : public Rpc_object<Typed_root<SESSION_TYPE> >,
 		/**
 		 * Return allocator to allocate server object in '_create_session()'
 		 */
-		Allocator      *md_alloc() { return _md_alloc; }
+		Allocator *md_alloc() { return _md_alloc; }
-		Rpc_entrypoint *ep()       { return _ep; }
+
+		/**
+		 * Return entrypoint that serves the root component
+		 */
+		Rpc_entrypoint *ep() { return _ep; }
 
 	public:
 

repos/base/include/session/session.h

@@ -26,12 +26,15 @@ namespace Genode { class Session; }
 
 /**
  * Base class of session interfaces
- *
- * Each session interface must implement the function 'service_name'
- * ! static const char *service_name();
- * This function returns the name of the service provided via the session
- * interface.
  */
-class Genode::Session { };
+class Genode::Session
+{
+	/*
+	 * Each session interface must implement the class function 'service_name'
+	 * ! static const char *service_name();
+	 * This function returns the name of the service provided via the session
+	 * interface.
+	 */
+};
 
 #endif /* _INCLUDE__SESSION_H_ */

repos/base/include/signal_session/signal_session.h

@@ -76,7 +76,7 @@ struct Genode::Signal_session : Session
 	 * but by using it as argument to our trusted signal-session
 	 * interface. Otherwise, a potential signal receiver could supply
 	 * a capability with a blocking interface to compromise the
-	 * nonblocking behaviour of the submit function.
+	 * nonblocking behaviour of the signal submission.
 	 */
 	virtual void submit(Signal_context_capability context,
 	                    unsigned cnt = 1) = 0;

repos/base/include/signal_session/source.h

@@ -27,7 +27,7 @@ namespace Genode { struct Signal_source; }
 /**
  * Blocking part of the signal-session interface
  *
- * The blocking 'wait_for_signal()' function cannot be part of the
+ * The blocking 'wait_for_signal()' operation cannot be part of the
  * signal-session interface because otherwise, context allocations or
  * signal submissions would not be possible while blocking for signals.
  * Therefore, the blocking part is implemented a separate interface,

repos/base/include/util/arg_string.h

@@ -61,7 +61,7 @@ class Genode::Arg
 		 * \param  out_sign     1 if positive; -1 if negative
 		 * \return              true if no syntactic anomaly occured
 		 *
-		 * This function handles the numberic modifiers G (2^30),
+		 * This method handles the numberic modifiers G (2^30),
 		 * M (2^20), and K (2^10).
 		 */
 		bool read_ulong(unsigned long *out_value, int *out_sign) const
@@ -228,7 +228,7 @@ class Genode::Arg_string
 		/**
 		 * Append source string to destination string
 		 *
-		 * NOTE: check string length before calling this function!
+		 * NOTE: check string length before calling this method!
 		 *
 		 * \return  last character of result string
 		 */

repos/base/include/util/avl_string.h

@@ -32,6 +32,11 @@ class Genode::Avl_string_base : public Avl_node<Avl_string_base>
 
 	protected:
 
+		/**
+		 * Constructor
+		 *
+		 * \noapi
+		 */
 		Avl_string_base(const char *str) : _str(str) { }
 
 	public:

repos/base/include/util/avl_tree.h

@@ -43,16 +43,16 @@ class Genode::Avl_node_base
 			 * \retval false if n2 is lower than n1
 			 * \retval true  if n2 is higher than or equal to n1
 			 *
-			 * This function must be provided by the derived class.
+			 * This method must be provided by the derived class.
-			 * It determines the order of nodes inside the avl tree.
+			 * It determines the order of nodes inside the AVL tree.
 			 */
 			virtual bool higher(Avl_node_base *n1, Avl_node_base *n2) const = 0;
 
 			/**
 			 * Node recomputation hook
 			 *
-			 * If a node gets rearranged, this function is called.
+			 * If a node gets rearranged, this method is called.
-			 * It can be used to update avl-tree-position dependent
+			 * It can be used to update AVL-tree-position dependent
 			 * meta data.
 			 */
 			virtual void recompute(Avl_node_base *) { }
@@ -137,30 +137,37 @@ class Genode::Avl_node_base
  *
  * \param NT  type of the class derived from 'Avl_node'
  *
- * Each object to be stored in the avl tree must be derived from
+ * Each object to be stored in the AVL tree must be derived from 'Avl_node'.
- * 'Avl_node'. The type of the derived class is to be specified as
+ * The type of the derived class is to be specified as template argument to
- * template argument to enable 'Avl_node' to call virtual functions
+ * enable 'Avl_node' to call virtual methods specific for the derived class.
- * specific for the derived class.
+ *
+ * The NT class must implement a method called 'higher' that takes a pointer to
+ * another NT object as argument and returns a bool value. The bool value is
+ * true if the specified node is higher or equal in the tree order.
  */
 template <typename NT>
-class Genode::Avl_node : public Avl_node_base
+struct Genode::Avl_node : Avl_node_base
 {
-	public:
+	/**
+	 * Return child of specified side, or nullptr if there is no child
+	 *
+	 * This method can be called by the NT objects to traverse the tree.
+	 */
+	inline NT *child(Side i) const { return static_cast<NT *>(_child[i]); }
 
-		inline NT *child(Side i) const { return static_cast<NT *>(_child[i]); }
+	/**
-
+	 * Default policy
-		/**
+	 *
-		 * Default policy
+	 * \noapi
-		 */
+	 */
-		void recompute() { }
+	void recompute() { }
 };
 
 
 /**
  * Root node of the AVL tree
  *
- * The real nodes are always attached at the left branch of
+ * The real nodes are always attached at the left branch of this root node.
- * this root node.
  */
 template <typename NT>
 class Genode::Avl_tree : Avl_node<NT>
@@ -199,8 +206,7 @@ class Genode::Avl_tree : Avl_node<NT>
 		/**
 		 * Request first node of the tree
 		 *
-		 * \return  first node
+		 * \return  first node, or nullptr if the tree is empty
-		 * \retval  NULL if tree is empty
 		 */
 		inline NT *first() const { return this->child(Avl_node<NT>::LEFT); }
 };

repos/base/include/util/bit_allocator.h

@@ -28,6 +28,11 @@ class Genode::Bit_allocator
 		addr_t          _next;
 		Bit_array<BITS> _array;
 
+		/**
+		 * Reserve consecutive number of bits
+		 *
+		 * \noapi
+		 */
 		void _reserve(addr_t bit_start, size_t const num)
 		{
 			if (!num) return;

repos/base/include/util/fifo.h

@@ -71,8 +71,6 @@ class Genode::Fifo
 
 		/**
 		 * Constructor
-		 *
-		 * Start with an empty list.
 		 */
 		Fifo(): _head(0), _tail(0) { }
 
@@ -130,7 +128,7 @@ class Genode::Fifo
 		}
 
 		/**
-		 * Obtain head element of the queue and remove element from queue
+		 * Remove head element from queue
 		 *
 		 * \return  head element or 0 if queue is empty
 		 */

repos/base/include/util/list.h

@@ -57,8 +57,6 @@ class Genode::List
 
 		/**
 		 * Constructor
-		 *
-		 * Start with an empty list.
 		 */
 		List() : _first(0) { }
 

repos/base/include/util/mmio.h

@@ -23,7 +23,7 @@ namespace Genode { class Mmio; }
 /**
  * A continuous MMIO region
  *
- * For correct behavior of the member functions of 'Mmio', a class that
+ * For correct behavior of the methods of 'Mmio', a class that
  * derives from one of the subclasses of 'Mmio' must not define members
  * named 'Register_base', 'Bitfield_base', 'Register_array_base' or
  * 'Array_bitfield_base'.

repos/base/include/util/noncopyable.h

@@ -28,12 +28,27 @@ class Genode::Noncopyable
 {
 	private:
 
+		/**
+		 * Constructor
+		 */
 		Noncopyable(const Noncopyable&);
+
 		const Noncopyable& operator=(const Noncopyable&);
 
 	protected:
 
+		/**
+		 * Constructor
+		 *
+		 * \noapi
+		 */
 		Noncopyable()  {}
+
+		/**
+		 * Destructor
+		 *
+		 * \noapi
+		 */
 		~Noncopyable() {}
 };
 

repos/base/include/util/string.h

@@ -1,5 +1,5 @@
 /*
- * \brief  String utility functions
+ * \brief  String utilities
  * \author Norman Feske
  * \author Sebastian Sumpf
  * \date   2006-05-10
@@ -59,7 +59,7 @@ class Genode::Number_of_bytes
 namespace Genode {
 
 	/**
-	 * Determine length of null-terminated string
+	 * Return length of null-terminated string in bytes
 	 */
 	inline size_t strlen(const char *s)
 	{
@@ -75,9 +75,9 @@ namespace Genode {
 	 * \param len   maximum number of characters to compare,
 	 *              default is unlimited
 	 *
-	 * \retval   0  strings are equal
+	 * \return   0 if both strings are equal, or
-	 * \retval  >0  s1 is higher than s2
+	 *           a positive number if s1 is higher than s2, or
-	 * \retval  <0  s1 is lower than s2
+	 *           a negative number if s1 is lower than s2
 	 */
 	inline int strcmp(const char *s1, const char *s2, size_t len = ~0UL)
 	{
@@ -87,7 +87,7 @@ namespace Genode {
 
 
 	/**
-	 * Simple memmove
+	 * Copy memory buffer to a potentially overlapping destination buffer
 	 *
 	 * \param dst   destination memory block
 	 * \param src   source memory block
@@ -110,7 +110,7 @@ namespace Genode {
 
 
 	/**
-	 * Copy memory block
+	 * Copy memory buffer to a non-overlapping destination buffer
 	 *
 	 * \param dst   destination memory block
 	 * \param src   source memory block
@@ -158,11 +158,11 @@ namespace Genode {
 	 * \param size  maximum number of characters to copy
 	 * \return      pointer to destination string
 	 *
-	 * This function is not fully compatible to the C standard, in particular
+	 * Note that this function is not fully compatible to the C standard, in
-	 * there is no zero-padding if the length of 'src' is smaller than 'size'.
+	 * particular there is no zero-padding if the length of 'src' is smaller
-	 * Furthermore, in contrast to the libc version, this function always
+	 * than 'size'. Furthermore, in contrast to the libc version, this function
-	 * produces a null-terminated string in the 'dst' buffer if the 'size'
+	 * always produces a null-terminated string in the 'dst' buffer if the
-	 * argument is greater than 0.
+	 * 'size' argument is greater than 0.
 	 */
 	inline char *strncpy(char *dst, const char *src, size_t size)
 	{
@@ -191,9 +191,9 @@ namespace Genode {
 	/**
 	 * Compare memory blocks
 	 *
-	 * \retval  0  memory blocks are equal
+	 * \return  0 if both memory blocks are equal, or
-	 * \retval <0  first memory block is less than second one
+	 *          a negative number if 'p0' is less than 'p1', or
-	 * \retval >0  first memory block is greater than second one
+	 *          a positive number if 'p0' is greater than 'p1'
 	 */
 	inline int memcmp(const void *p0, const void *p1, size_t size)
 	{
@@ -209,7 +209,11 @@ namespace Genode {
 
 
 	/**
-	 * Memset
+	 * Fill destination buffer with given value
+	 *
+	 * \param dst   destination buffer
+	 * \param i     byte value
+	 * \param size  buffer size in bytes
 	 */
 	inline void *memset(void *dst, int i, size_t size)
 	{

repos/base/include/util/token.h

@@ -121,10 +121,10 @@ class Genode::Token
 		 *
 		 * \param  max_len  maximum token length
 		 *
-		 * This function is used during the construction of 'Token'
+		 * This method is used during the construction of 'Token'
 		 * objects, in particular for determining the value of the '_len'
 		 * member. Therefore, we explicitely pass the 'max_len' to the
-		 * function. For the public interface, there exists the 'type()'
+		 * method. For the public interface, there exists the 'type()'
 		 * accessor, which relies on '_len' as implicit argument.
 		 */
 		Type _type(size_t max_len) const

repos/base/include/x86/cpu/string.h

@@ -1,5 +1,5 @@
 /*
- * \brief  Cpu specifi memcpy
+ * \brief  CPU-specific memcpy
  * \author Sebastian Sumpf
  * \date   2012-08-02
  */
@@ -23,7 +23,7 @@ namespace Genode {
 	 * \param src   source memory block
 	 * \param size  number of bytes to copy
 	 *
-	 * \return      Number of bytes not copied
+	 * \return      number of bytes not copied
 	 */
 	inline size_t memcpy_cpu(void *, const void *, size_t size) { return size; }
 }

repos/os/include/block/driver.h

@@ -205,7 +205,7 @@ class Block::Driver
 		 * Informs the driver that the client session was closed
 		 *
 		 * Note: drivers with state (e.g. asynchronously working)
-		 *       should override this function, and reset their internal state
+		 *       should override this method, and reset their internal state
 		 */
 		virtual void session_invalidated() { }
 

repos/os/include/block_session/block_session.h

@@ -2,16 +2,6 @@
  * \brief  Block session interface.
  * \author Stefan Kalkowski
  * \date   2010-07-06
- *
- * A block session corresponds to a block device, that can be used to read
- * or store data. Payload is communicated over the packet-stream interface
- * set up between 'Session_client' and 'Session_server'.
- *
- * Even though the functions 'tx' and 'tx_channel' are specific for the client
- * side of the block session interface, they are part of the abstract 'Session'
- * class to enable the client-side use of the block interface via a pointer to
- * the abstract 'Session' class. This way, we can transparently co-locate the
- * packet-stream server with the client in same program.
  */
 
 /*
@@ -41,8 +31,9 @@ namespace Block {
 
 
 /**
- * Represents an operation request with respect to a block,
+ * Represents an block-operation request
- * the data associated with the 'Packet_descriptor' is either
+ *
+ * The data associated with the 'Packet_descriptor' is either
  * the data read from or written to the block indicated by
  * its number.
  */
@@ -91,6 +82,19 @@ class Block::Packet_descriptor : public Genode::Packet_descriptor
 };
 
 
+/*
+ * Block session interface
+ *
+ * A block session corresponds to a block device that can be used to read
+ * or store data. Payload is communicated over the packet-stream interface
+ * set up between 'Session_client' and 'Session_server'.
+ *
+ * Even though the methods 'tx' and 'tx_channel' are specific for the client
+ * side of the block session interface, they are part of the abstract 'Session'
+ * class to enable the client-side use of the block interface via a pointer to
+ * the abstract 'Session' class. This way, we can transparently co-locate the
+ * packet-stream server with the client in same program.
+ */
 struct Block::Session : public Genode::Session
 {
 	enum { TX_QUEUE_SIZE = 256 };

repos/os/include/block_session/rpc_object.h

@@ -43,7 +43,7 @@ class Block::Session_rpc_object : public Genode::Rpc_object<Session, Session_rpc
 		/**
 		 * Return capability to packet-stream channel
 		 *
-		 * This function is called by the client via an RPC call at session
+		 * This method is called by the client via an RPC call at session
 		 * construction time.
 		 */
 		Genode::Capability<Tx> _tx_cap() { return _tx.cap(); }

repos/os/include/cli_monitor/child.h

@@ -188,7 +188,7 @@ class Child_base : public Genode::Child_policy
 		/**
 		 * Try to respond to a current resource request issued by the child
 		 *
-		 * This function evaluates the conditions, under which a resource
+		 * This method evaluates the conditions, under which a resource
 		 * request can be answered: There must be enough room between the
 		 * current quota and the configured limit, and there must be enough
 		 * slack memory available. If both conditions are met, the quota
@@ -236,7 +236,7 @@ class Child_base : public Genode::Child_policy
 		/**
 		 * Return RAM quota status of the child
 		 *
-		 * XXX should be a const function, but the 'Ram_session' accessors
+		 * XXX should be a const method, but the 'Ram_session' accessors
 		 *     are not const
 		 */
 		Ram_status ram_status()

repos/os/include/decorator/window.h

@@ -203,7 +203,7 @@ class Decorator::Window_base : public Window_list::Element
 		 * \return true if window changed
 		 *
 		 * We do not immediately update the views as part of the update
-		 * function because at the time when updating the model, the
+		 * method because at the time when updating the model, the
 		 * decorations haven't been redrawn already. If we updated the
 		 * nitpicker views at this point, we would reveal not-yet-drawn pixels.
 		 */

repos/os/include/decorator/window_stack.h

@@ -70,7 +70,7 @@ class Decorator::Window_stack
 		/**
 		 * Generate window list in reverse order
 		 *
-		 * After calling this function, the '_windows' list is empty.
+		 * After calling this method, the '_windows' list is empty.
 		 */
 		Window_list _reversed_window_list()
 		{

repos/os/include/file_system_session/rpc_object.h

@@ -41,7 +41,7 @@ class File_system::Session_rpc_object : public Genode::Rpc_object<Session, Sessi
 		/**
 		 * Return capability to packet-stream channel
 		 *
-		 * This function is called by the client via an RPC call at session
+		 * This method is called by the client via an RPC call at session
 		 * construction time.
 		 */
 		Capability<Tx> _tx_cap() { return _tx.cap(); }

repos/os/include/framebuffer_session/connection.h

@@ -62,7 +62,7 @@ class Framebuffer::Connection : public Genode::Connection<Session>,
 		 *
 		 * The specified values are not enforced. After creating the
 		 * session, you should validate the actual frame-buffer attributes
-		 * by calling the 'info' function of the frame-buffer interface.
+		 * by calling the 'info' method of the frame-buffer interface.
 		 */
 		Connection(unsigned     width  = 0,
 		           unsigned     height = 0,

repos/os/include/framebuffer_session/framebuffer_session.h

@@ -76,9 +76,9 @@ struct Framebuffer::Session : Genode::Session
 	/**
 	 * Request dataspace representing the logical frame buffer
 	 *
-	 * By calling this function, the framebuffer client enables the server
+	 * By calling this method, the framebuffer client enables the server
 	 * to reallocate the framebuffer dataspace (e.g., on mode changes).
-	 * Hence, prior calling this function, the client should make sure to
+	 * Hence, prior calling this method, the client should make sure to
 	 * have detached the previously requested dataspace from its local
 	 * address space.
 	 */
@@ -86,7 +86,7 @@ struct Framebuffer::Session : Genode::Session
 
 	/**
 	 * Request display-mode properties of the framebuffer ready to be
-	 * obtained via the 'dataspace()' function
+	 * obtained via the 'dataspace()' method
 	 */
 	virtual Mode mode() const = 0;
 
@@ -98,7 +98,7 @@ struct Framebuffer::Session : Genode::Session
 	 * get resized according to the window dimensions. By installing a
 	 * signal handler for mode changes, the framebuffer client can respond
 	 * to such changes. The new mode can be obtained using the 'mode()'
-	 * function. However, from the client's perspective, the original mode
+	 * method. However, from the client's perspective, the original mode
 	 * stays in effect until the it calls 'dataspace()' again.
 	 */
 	virtual void mode_sigh(Genode::Signal_context_capability sigh) = 0;

repos/os/include/init/child.h

@@ -132,7 +132,7 @@ namespace Init {
 		Genode::size_t const child_name_len = Genode::strlen(child_name);
 
 		/*
-		 * If the function was called with a valid "label" string, the
+		 * If the method was called with a valid "label" string, the
 		 * following condition should be always satisfied. See the
 		 * comment in 'service_node_args_condition_satisfied'.
 		 */
@@ -180,7 +180,7 @@ namespace Init {
 			 * Skip child-name prefix if the key is the process "label".
 			 *
 			 * Because 'filter_session_args' is called prior the call of
-			 * 'resolve_session_request' from the 'Child::session' function,
+			 * 'resolve_session_request' from the 'Child::session' method,
 			 * 'args' contains the filtered arguments, in particular the label
 			 * prefixed with the child's name. For the 'if-args' declaration,
 			 * however, we want to omit specifying this prefix because the
@@ -261,7 +261,7 @@ class Init::Routed_service : public Genode::Service
 		                                   Genode::Affinity const &affinity)
 		{
 			/*
-			 * This function is called from the context of the client's
+			 * This method is called from the context of the client's
 			 * activation thread. If the service is not yet announced,
 			 * we let the client block.
 			 */

repos/os/include/init/child_config.h

@@ -122,7 +122,7 @@ class Init::Child_config
 		/**
 		 * Return file name if configuration comes from a file
 		 *
-		 * If the configuration is provided inline, the function returns 0.
+		 * If the configuration is provided inline, the method returns 0.
 		 */
 		char const *filename() const {
 			return _filename[0] != 0 ? _filename : 0; }
@@ -130,7 +130,7 @@ class Init::Child_config
 		/**
 		 * Request dataspace holding the start node's configuration data
 		 *
-		 * This function returns a valid dataspace only when using an
+		 * This method returns a valid dataspace only when using an
 		 * inline configuration (if 'filename()' returns 0).
 		 */
 		Genode::Dataspace_capability dataspace() {

repos/os/include/init/child_policy.h

@@ -47,7 +47,7 @@ class Init::Child_policy_ram_phys
 		/**
 		 * Filter arguments of session request
 		 *
-		 * This function removes phys_start and phys_size ram_session
+		 * This method removes phys_start and phys_size ram_session
 		 * parameters if the child configuration does not explicitly
 		 * permits this.
 		 */
@@ -86,7 +86,7 @@ class Init::Child_policy_enforce_labeling
 		/**
 		 * Filter arguments of session request
 		 *
-		 * This function modifies the 'label' argument and leaves all other
+		 * This method modifies the 'label' argument and leaves all other
 		 * session arguments intact.
 		 */
 		void filter_session_args(const char *, char *args,

repos/os/include/ldso/arch.h

@@ -1,5 +1,5 @@
 /*
- * \brief  Architecture specific functions
+ * \brief  Architecture-specific functions
  * \author Sebastian Sumpf
  * \date   2009-10-26
  */

repos/os/include/loader_session/loader_session.h

@@ -106,7 +106,7 @@ struct Loader::Session : Genode::Session
 	/**
 	 * Constrain size of the nitpicker buffer used by the subsystem
 	 *
-	 * Calling this function prior 'start()' enables the virtualization
+	 * Calling this method prior 'start()' enables the virtualization
 	 * of the nitpicker session interface.
 	 */
 	virtual void constrain_geometry(Area size) = 0;
@@ -134,7 +134,7 @@ struct Loader::Session : Genode::Session
 	 * the possible types of faults, please refer to the documentation of
 	 * 'Rm_session::fault_handler' and 'Cpu_session::exception_handler'.
 	 *
-	 * This function should not be called after the 'start' function.
+	 * This method should not be called after the 'start' method.
 	 */
 	virtual void fault_sigh(Signal_context_capability sigh) = 0;
 

repos/os/include/net/arp.h

@@ -266,7 +266,7 @@ class Net::Arp_packet
 
 
 		/***************************
-		 ** convenience functions **
+		 ** Convenience functions **
 		 ***************************/
 
 		/**

repos/os/include/net/dhcp.h

@@ -252,9 +252,9 @@ class Net::Dhcp_packet
 			mac.copy(&_chaddr); }
 
 
-		/***************************
+		/*************************
-		 ** Convenience functions **
+		 ** Convenience methods **
-		 ***************************/
+		 *************************/
 
 		static bool is_dhcp(Udp_packet *udp)
 		{

repos/os/include/net/netaddress.h

@@ -43,9 +43,9 @@ class Net::Network_address
 			Genode::memcpy(&addr, src, LEN); }
 
 
-		/***********************
+		/*********************
-		 ** Helper functions  **
+		 ** Helper methods  **
-		 ***********************/
+		 *********************/
 
 		void copy(void *dst) { Genode::memcpy(dst, addr, LEN); }
 

repos/os/include/nic/driver.h

@@ -70,7 +70,7 @@ struct Nic::Driver : Genode::Irq_handler
 	 * \param packet start of packet
 	 * \param size   packet size
 	 *
-	 * If the packet size is not a multiple of 4 bytes, this function
+	 * If the packet size is not a multiple of 4 bytes, this method
 	 * accesses the bytes after the packet buffer up to the next 4-byte
 	 * length (in the worst case, 3 bytes after the packet end).
 	 */

repos/os/include/nic_session/nic_session.h

@@ -2,18 +2,6 @@
  * \brief  NIC session interface
  * \author Norman Feske
  * \date   2009-11-13
- *
- * A NIC session corresponds to a network adaptor, which can be used to
- * transmit and receive network packets. Payload is communicated over the
- * packet-stream interface set up between 'Session_client' and
- * 'Session_server'.
- *
- * Even though the functions 'tx', 'tx_channel', 'rx', and 'rx_channel' are
- * specific for the client side of the NIC session interface, they are part of
- * the abstract 'Session' class to enable the client-side use of the NIC
- * interface via a pointer to the abstract 'Session' class. This way, we can
- * transparently co-locate the packet-stream server with the client in same
- * program.
  */
 
 /*
@@ -48,6 +36,21 @@ namespace Nic {
 struct Nic::Mac_address { char addr[6]; };
 
 
+/*
+ * NIC session interface
+ *
+ * A NIC session corresponds to a network adaptor, which can be used to
+ * transmit and receive network packets. Payload is communicated over the
+ * packet-stream interface set up between 'Session_client' and
+ * 'Session_server'.
+ *
+ * Even though the methods 'tx', 'tx_channel', 'rx', and 'rx_channel' are
+ * specific for the client side of the NIC session interface, they are part of
+ * the abstract 'Session' class to enable the client-side use of the NIC
+ * interface via a pointer to the abstract 'Session' class. This way, we can
+ * transparently co-locate the packet-stream server with the client in same
+ * program.
+ */
 struct Nic::Session : Genode::Session
 {
 	enum { QUEUE_SIZE = 1024 };

repos/os/include/nitpicker_session/client.h

@@ -90,7 +90,7 @@ class Nitpicker::Session_client : public Genode::Rpc_client<Session>
 		 * Enqueue command to command buffer
 		 *
 		 * The submitted command is not executed immediately. To execute a
-		 * batch of enqueued commands, the 'execute' function must be called.
+		 * batch of enqueued commands, the 'execute' method must be called.
 		 * Only in the corner case when there is not space left in the command
 		 * buffer, the 'execute' is called to make room in the buffer.
 		 */

repos/os/include/nitpicker_session/nitpicker_session.h

@@ -41,7 +41,7 @@ struct Nitpicker::Session : Genode::Session
 	/**
 	 * Session-local view handle
 	 *
-	 * When issuing commands to nitpicker via the 'execute' function, views
+	 * When issuing commands to nitpicker via the 'execute' method, views
 	 * are referenced by session-local handles.
 	 */
 	typedef Genode::Handle<View> View_handle;
@@ -155,7 +155,7 @@ struct Nitpicker::Session : Genode::Session
 			 * Enqueue command
 			 *
 			 * The command will be dropped if the buffer is full. Check for this
-			 * condition by calling 'is_full()' prior calling this function.
+			 * condition by calling 'is_full()' prior calling this method.
 			 */
 			void enqueue(Command const &command)
 			{
@@ -213,8 +213,8 @@ struct Nitpicker::Session : Genode::Session
 	/**
 	 * Return session-local handle for the specified view
 	 *
-	 * The handle returned by this functions can be used to issue commands
+	 * The handle returned by this method can be used to issue commands
-	 * via the 'execute' function.
+	 * via the 'execute' method.
 	 *
 	 * \param handle  designated view handle to be assigned to the imported
 	 *                view. By default, a new handle will be allocated.
@@ -269,7 +269,7 @@ struct Nitpicker::Session : Genode::Session
 	 * Set focused session
 	 *
 	 * Normally, the focused session is defined by the user by clicking on a
-	 * view. The 'focus' function allows a client to set the focus without user
+	 * view. The 'focus' method allows a client to set the focus without user
 	 * action. However, the change of the focus is performed only is the
 	 * currently focused session belongs to a child or the same process as the
 	 * called session. This relationship is checked by comparing the session

repos/os/include/os/alarm.h

@@ -32,7 +32,7 @@ class Genode::Alarm
 
 		friend class Alarm_scheduler;
 
-		Lock             _dispatch_lock;  /* taken during handle function */
+		Lock             _dispatch_lock;  /* taken during handle method   */
 		Time             _deadline;       /* next deadline                */
 		Time             _period;         /* duration between alarms      */
 		int              _active;         /* set to one when active       */
@@ -48,9 +48,9 @@ class Genode::Alarm
 	protected:
 
 		/**
-		 * Function to be called on when deadline is reached
+		 * Method to be called on when deadline is reached
 		 *
-		 * This function must be implemented by a derived class.  If the
+		 * This method must be implemented by a derived class.  If the
 		 * return value is 'true' and the alarm is periodically scheduled,
 		 * the alarm is scheduled again.
 		 */
@@ -68,14 +68,14 @@ class Genode::Alarm_scheduler
 {
 	private:
 
-		Lock         _lock;   /* protect alarm list                       */
+		Lock         _lock;   /* protect alarm list                     */
-		Alarm       *_head;   /* head of alarm list                       */
+		Alarm       *_head;   /* head of alarm list                     */
-		Alarm::Time  _now;    /* recent time (updated by handle function) */
+		Alarm::Time  _now;    /* recent time (updated by handle method) */
 
 		/**
 		 * Enqueue alarm into alarm queue
 		 *
-		 * This is a helper function for 'schedule' and 'handle'.
+		 * This is a helper for 'schedule' and 'handle'.
 		 */
 		void _unsynchronized_enqueue(Alarm *alarm);
 

repos/os/include/os/attached_dataspace.h

@@ -86,7 +86,7 @@ class Genode::Attached_dataspace : Noncopyable
 		/**
 		 * Forget dataspace, thereby skipping the detachment on destruction
 		 *
-		 * This function can be called if the the dataspace is known to be
+		 * This method can be called if the the dataspace is known to be
 		 * physically destroyed, e.g., because the session where the dataspace
 		 * originated from was closed. In this case, core will already have
 		 * removed the memory mappings of the dataspace. So we have to omit the

repos/os/include/os/attached_ram_dataspace.h

@@ -2,13 +2,6 @@
  * \brief  RAM dataspace utility
  * \author Norman Feske
  * \date   2008-03-22
- *
- * The combination of RAM allocation and a local RM attachment
- * is a frequent use case. Each function may fail, which makes
- * error handling inevitable. This utility class encapsulates
- * this functionality to handle both operations as a transaction.
- * When embedded as a member, this class also takes care about
- * freeing and detaching the dataspace at destruction time.
  */
 
 /*
@@ -28,6 +21,15 @@
 namespace Genode { class Attached_ram_dataspace; }
 
 
+/*
+ * Utility for allocating and attaching a RAM dataspace
+ *
+ * The combination of RAM allocation and a local RM attachment is a frequent
+ * use case. Each function may fail, which makes error handling inevitable.
+ * This utility class encapsulates this functionality to handle both operations
+ * as a transaction. When embedded as a member, this class also takes care
+ * about freeing and detaching the dataspace at destruction time.
+ */
 class Genode::Attached_ram_dataspace
 {
 	private:

repos/os/include/os/attached_rom_dataspace.h

@@ -47,7 +47,7 @@ class Genode::Attached_rom_dataspace
 			 * '_rom.dataspace()'.
 			 *
 			 * The ROM server may destroy the original dataspace when the
-			 * 'dataspace()' function is called. In this case, all existing
+			 * 'dataspace()' method is called. In this case, all existing
 			 * mappings of the dataspace will be flushed by core. A destruction
 			 * of 'Attached_dataspace' after this point will attempt to detach
 			 * the already flushed mappings, thereby producing error messages

repos/os/include/os/child_policy_dynamic_rom.h

@@ -34,7 +34,7 @@ class Genode::Child_policy_dynamic_rom_file : public Rpc_object<Rom_session>,
 		 * e.g., written by the main thread and consumed by the child's
 		 * entrypoint that manages the local ROM service for handing out a
 		 * dynamic config. Hence, the '_lock' is used to synchronize the
-		 * 'load' and 'dataspace' functions.
+		 * 'load' and 'dataspace' methods.
 		 */
 		Lock _lock;
 
@@ -156,9 +156,9 @@ class Genode::Child_policy_dynamic_rom_file : public Rpc_object<Rom_session>,
 		void close(Session_capability) { }
 
 
-		/*********************
+		/**********************
-		 ** Policy function **
+		 ** Policy interface **
-		 *********************/
+		 **********************/
 
 		Service *resolve_session_request(const char *service_name,
 		                                 const char *args)

repos/os/include/os/config.h

@@ -57,7 +57,7 @@ class Genode::Config
 		 *
 		 * \throw Invalid  if the new configuration has an invalid syntax
 		 *
-		 * This function is meant to be called as response to a signal
+		 * This method is meant to be called as response to a signal
 		 * received by the signal handler as registered via 'sigh()'.
 		 */
 		void reload();

repos/os/include/os/handle_registry.h

@@ -60,7 +60,7 @@ class Genode::Handle
  * \param OBJ     type of context associated with a handle
  *
  * The constructor of the 'HANDLE' type must take an unsigned value as argument
- * and have a 'value()' function that returns the same value.
+ * and have a 'value()' method that returns the same value.
  *
  * The 'OBJ' type must be inherited from 'Weak_object'.
  */

repos/os/include/os/irq_activation.h

@@ -70,7 +70,7 @@ class Genode::Irq_activation : Thread_base
 		}
 
 		/**
-		 * Thread entry function
+		 * Thread entry
 		 *
 		 * The interrupt thread infinitely waits for interrupts and calls
 		 * the handler on occurrence.

repos/os/include/os/packet_allocator.h

@@ -134,9 +134,9 @@ class Genode::Packet_allocator : public Genode::Range_allocator
 		}
 
 
-		/*********************
+		/*************
-		 ** Dummy functions **
+		 ** Dummies **
-		 *********************/
+		 *************/
 
 		bool need_size_for_free() const override { return false; }
 		void free(void *addr) { }

repos/os/include/os/packet_stream.h

@@ -58,7 +58,7 @@
  *   empty acknowledgement queue and delivers a 'ack_avail' signal.
  *
  * These conditions can be avoided by querying the state of the submit and
- * acknowledge buffers using the functions 'packet_avail',
+ * acknowledge buffers using the methods 'packet_avail',
  * 'ready_to_submit', 'ready_to_ack', and 'ack_avail'.
  *
  * If bidirectional data exchange between two processes is desired, two pairs
@@ -407,10 +407,7 @@ class Genode::Packet_descriptor_receiver
 
 
 /**
- * Helper class for 'Packet_stream_source' and 'Packet_stream_sink'
+ * Common base of 'Packet_stream_source' and 'Packet_stream_sink'
- * containing code shared between both classes.
- *
- * This class is private to the packet-stream interface.
  */
 class Genode::Packet_stream_base
 {
@@ -802,7 +799,7 @@ class Genode::Packet_stream_sink : private Packet_stream_base
 		/**
 		 * Get next packet from source
 		 *
-		 * This function blocks if no packets are available.
+		 * This method blocks if no packets are available.
 		 */
 		Packet_descriptor get_packet()
 		{
@@ -839,7 +836,7 @@ class Genode::Packet_stream_sink : private Packet_stream_base
 		/**
 		 * Tell the source that the processing of the specified packet is completed
 		 *
-		 * This function blocks if the acknowledgement queue is full.
+		 * This method blocks if the acknowledgement queue is full.
 		 */
 		void acknowledge_packet(Packet_descriptor packet)
 		{

repos/os/include/os/ring_buffer.h

@@ -86,8 +86,7 @@ class Ring_buffer
 		/**
 		 * Place element into ring buffer
 		 *
-		 * If the ring buffer is full, this function
+		 * \throw Overflow  the ring buffer is full
-		 * throws an Overflow exception.
 		 */
 		void add(ET ev)
 		{
@@ -106,8 +105,8 @@ class Ring_buffer
 		 *
 		 * \return  element
 		 *
-		 * If the ring buffer is empty, this function
+		 * If the ring buffer is empty, this method blocks until an element
-		 * blocks until an element gets available.
+		 * gets available.
 		 */
 		ET get()
 		{

repos/os/include/os/signal_rpc_dispatcher.h

@@ -133,13 +133,13 @@ namespace Server{
 
 
 /**
- * Signal dispatcher for directing signals via RPC to member function
+ * Signal dispatcher for directing signals via RPC to object methods
  *
- * This utility associates member functions with signals. It is intended to
+ * This utility associates object methods with signals. It is intended to
  * be used as a member variable of the class that handles incoming signals
  * of a certain type. The constructor takes a pointer-to-member to the
- * signal handling function as argument. If a signal is received at the
+ * signal-handling method as argument. If a signal is received at the
- * common signal reception code, this function will be invoked by calling
+ * common signal reception code, this method will be invoked by calling
  * 'Signal_dispatcher_base::dispatch'.
  *
  * \param T  type of signal-handling class
@@ -157,7 +157,7 @@ struct Genode::Signal_rpc_member : Genode::Signal_rpc_dispatcher_base,
 	 * Constructor
 	 *
 	 * \param ep          entrypoint managing this signal RPC
-	 * \param obj,member  object and member function to call when
+	 * \param obj,member  object and method to call when
 	 *                    the signal occurs
 	 */
 	Signal_rpc_member(EP &ep, T &obj, void (T::*member)(unsigned))

repos/os/include/os/slave.h

@@ -44,7 +44,7 @@ class Genode::Slave_policy : public Genode::Child_policy
 		/**
 		 * Return white list of services the slave is permitted to use
 		 *
-		 * The list is terminated via a NULL pointer.
+		 * The list is terminated via a null pointer.
 		 */
 		virtual char const **_permitted_services() const = 0;
 

repos/os/include/os/static_root.h

@@ -2,10 +2,6 @@
  * \brief  Root component for singleton services
  * \author Norman Feske
  * \date   2012-10-05
- *
- * Many components, in particular device drivers, support only one client
- * at a time. In this case, one single session may be created right at the
- * start of the program and handed out via the 'Root::session' function.
  */
 
 /*
@@ -29,6 +25,10 @@ namespace Genode { template <typename> class Static_root; }
 
 /**
  * Root interface that hands out a statically created session
+ *
+ * Many components, in particular device drivers, support only one client
+ * at a time. In this case, one single session may be created right at the
+ * start of the program and handed out via the 'Root::session' method.
  */
 template <typename SESSION>
 class Genode::Static_root : public Genode::Rpc_object<Genode::Typed_root<SESSION> >

repos/os/include/os/surface.h

@@ -65,7 +65,7 @@ class Genode::Surface_base
 		/**
 		 * Register part of surface to be flushed
 		 *
-		 * This function is called by graphics primitives when surface regions
+		 * This method is called by graphics primitives when surface regions
 		 * are changed.
 		 */
 		void flush_pixels(Rect rect)

repos/os/include/os/synced_interface.h

@@ -1,14 +1,7 @@
 /*
- * \brief  Utility for synchronizing the access of interface functions
+ * \brief  Utility for synchronizing the access of interface methods
  * \author Norman Feske
  * \date   2013-05-16
- *
- * The 'Synced_interface' utility makes the serialization of interface
- * function calls easy. The 'Synced_interface' is a functor that takes a lock
- * and a pointer to an interface as arguments. When called, the functor
- * returns a smart pointer to the interface. When this smart pointer gets
- * dereferenced, the smart pointer takes care of acquiring and releasing
- * the lock while the interface function is executed.
  */
 
 #ifndef _INCLUDE__OS__SYNCED_INTERFACE_H_
@@ -23,6 +16,16 @@ namespace Genode {
 }
 
 
+/*
+ * Utility for synchronizing the access of interface methods
+ *
+ * The 'Synced_interface' utility makes the serialization of interface
+ * method calls easy. The 'Synced_interface' is a functor that takes a lock
+ * and a pointer to an interface as arguments. When called, the functor
+ * returns a smart pointer to the interface. When this smart pointer gets
+ * dereferenced, the smart pointer takes care of acquiring and releasing
+ * the lock while the interface method is executed.
+ */
 template <typename IF, typename LOCK>
 class Genode::Synced_interface
 {

repos/os/include/packet_stream_rx/rpc_object.h

@@ -59,7 +59,7 @@ class Packet_stream_rx::Rpc_object : public Genode::Rpc_object<CHANNEL, Rpc_obje
 		~Rpc_object() { _ep.dissolve(this); }
 
 		/*
-		 * The 'sigh_ack_avail()' and 'sigh_ready_to_submit()' functions
+		 * The 'sigh_ack_avail()' and 'sigh_ready_to_submit()' methods
 		 * may be called at session-creation time to override the default
 		 * data-flow signal handlers as provided by the packet-stream source.
 		 * The default handlers let the server block in the event of data
@@ -67,7 +67,7 @@ class Packet_stream_rx::Rpc_object : public Genode::Rpc_object<CHANNEL, Rpc_obje
 		 * implementation is able to avoid blocking for a single event by
 		 * facilitating the use of a select-like mode of operation.
 		 *
-		 * Note that calling these functions after the finished creation of
+		 * Note that calling these methods after the finished creation of
 		 * the session has no effect because the client queries the signal
 		 * handlers only once at session-creation time.
 		 */

repos/os/include/packet_stream_tx/packet_stream_tx.h

@@ -29,10 +29,10 @@ struct Packet_stream_tx::Channel
 	/**
 	 * Request transmission interface
 	 *
-	 * This function enables the client-side use of the 'Channel' using
+	 * This method enables the client-side use of the 'Channel' using
 	 * the abstract 'Channel' interface only. This is useful in cases
 	 * where both source and sink of the 'Channel' are co-located in
-	 * one program. At the server side of the 'Channel', this function
+	 * one program. At the server side of the 'Channel', this method
 	 * has no meaning.
 	 */
 	virtual Source *source() { return 0; }

repos/os/include/packet_stream_tx/rpc_object.h

@@ -58,7 +58,7 @@ class Packet_stream_tx::Rpc_object : public Genode::Rpc_object<CHANNEL, Rpc_obje
 		~Rpc_object() { _ep.dissolve(this); }
 
 		/*
-		 * The 'sigh_packet_avail()' and 'sigh_ready_to_ack()' functions
+		 * The 'sigh_packet_avail()' and 'sigh_ready_to_ack()' methods
 		 * may be called at session-creation time to override the default
 		 * data-flow signal handlers as provided by the packet-stream sink.
 		 * The default handlers let the server block in the event of data
@@ -66,7 +66,7 @@ class Packet_stream_tx::Rpc_object : public Genode::Rpc_object<CHANNEL, Rpc_obje
 		 * implementation is able to avoid blocking for a single event by
 		 * facilitating the use of a select-like mode of operation.
 		 *
-		 * Note that calling these functions after the finished creation of
+		 * Note that calling these methods after the finished creation of
 		 * the session has no effect because the client queries the signal
 		 * handlers only once at session-creation time.
 		 */

repos/os/include/pci_device/pci_device.h

@@ -150,10 +150,6 @@ struct Pci::Device
 	                          Access_size size) = 0;
 
 
-	/***************************
-	 ** Convenience functions **
-	 ***************************/
-
 	/*
 	 * The base classes are defined as follows:
 	 *

repos/os/include/pci_session/pci_session.h

@@ -51,7 +51,7 @@ struct Pci::Session : Genode::Session
 	/**
 	 * Free server-internal data structures representing the device
 	 *
-	 * Use this function to relax the heap partition of your PCI session.
+	 * Use this method to relax the heap partition of your PCI session.
 	 */
 	virtual void release_device(Device_capability device) = 0;
 

repos/os/include/platform/imx53/imx_framebuffer_session/connection.h

@@ -62,7 +62,7 @@ class Framebuffer::Imx_connection : public Genode::Connection<Imx_session>,
 		 *
 		 * The specified values are not enforced. After creating the
 		 * session, you should validate the actual frame-buffer attributes
-		 * by calling the 'info' function of the frame-buffer interface.
+		 * by calling the 'info' method of the frame-buffer interface.
 		 */
 		Imx_connection(unsigned     width  = 0,
 		               unsigned     height = 0,

repos/os/include/platform/rpi/platform_session/platform_session.h

@@ -34,7 +34,7 @@ struct Platform::Session : Genode::Session
 	 *
 	 * The 'info' argument serves as both input and output parameter. As input,
 	 * it describes the desired properties of the framebuffer. In return, the
-	 * function delivers the values that were actually taken into effect.
+	 * method delivers the values that were actually taken into effect.
 	 */
 	virtual void setup_framebuffer(Framebuffer_info &info) = 0;
 

repos/os/include/report_session/report_session.h

@@ -61,7 +61,7 @@ struct Report::Session : Genode::Session
 	 *
 	 * \param length  length of report in bytes
 	 *
-	 * While this function is called, the information in the dataspace
+	 * While this method is called, the information in the dataspace
 	 * must not be modified by the client.
 	 */
 	virtual void submit(size_t length) = 0;
@@ -74,7 +74,7 @@ struct Report::Session : Genode::Session
 	/**
 	 * Request a response from the recipient of reports
 	 *
-	 * By calling this function, the client expects that the server will
+	 * By calling this method, the client expects that the server will
 	 * replace the content of the dataspace with new information.
 	 *
 	 * \return length of response in bytes

repos/os/include/terminal/cell_array.h

@@ -23,7 +23,7 @@
  *              about the glyph and its attributes
  *
  * The 'CELL' type must have a default constructor and has to provide the
- * function 'set_cursor()' and 'clear_cursor'.
+ * methods 'set_cursor()' and 'clear_cursor'.
  */
 template <typename CELL>
 class Cell_array

repos/os/include/terminal_session/terminal_session.h

@@ -66,7 +66,7 @@ struct Terminal::Session : Genode::Session
 	/**
 	 * Register signal handler to be informed about the established connection
 	 *
-	 * This function is used for a simple startup protocol of terminal
+	 * This method is used for a simple startup protocol of terminal
 	 * sessions. At session-creation time, the terminal session may not
 	 * be ready to use. For example, a TCP terminal session needs an
 	 * established TCP connection first. However, we do not want to let the