[beast] BIRNET: docu cleanups

[Tim Janik <timj src gnome org>]

commit abfdc7732262dbd76cb1790bbf30c4d91bf220f3
Author: Tim Janik <timj gtk org>
Date:   Sun May 8 02:45:41 2011 +0200

    BIRNET: docu cleanups

 birnet/birnet.hh           |    6 ++++++
 birnet/birnetmsg.cc        |    2 +-
 birnet/birnettests.h       |    7 ++++---
 birnet/birnetthreadimpl.cc |   26 +++++++++++++-------------
 birnet/birnetutils.cc      |   28 +++++++++++++++-------------
 5 files changed, 39 insertions(+), 30 deletions(-)
---
diff --git a/birnet/birnet.hh b/birnet/birnet.hh
index 3b95ef8..0b7e6f6 100644
--- a/birnet/birnet.hh
+++ b/birnet/birnet.hh
@@ -28,5 +28,11 @@
 #include <birnet/birnetutils.hh>
 #include <birnet/birnetthread.hh>
 
+/**
+ * @namespace Birnet
+ * Library with utility functions, carried forward in Rapicorn: http://dev.testbit.eu/rapicorn/latest/
+ */
+namespace Birnet {}
+
 #endif /* __BIRNET_H__ */
 /* vim:set ts=8 sts=2 sw=2: */
diff --git a/birnet/birnetmsg.cc b/birnet/birnetmsg.cc
index 6dc0002..0600062 100644
--- a/birnet/birnetmsg.cc
+++ b/birnet/birnetmsg.cc
@@ -1,6 +1,6 @@
 /* Birnet
  * Copyright (C) 2006 Tim Janik
- * 
+ *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
  * License as published by the Free Software Foundation; either
diff --git a/birnet/birnettests.h b/birnet/birnettests.h
index cdaa331..652607d 100644
--- a/birnet/birnettests.h
+++ b/birnet/birnettests.h
@@ -259,7 +259,8 @@ tabort_handler (bool   set_values,
   TABORT_call();                                        \
 } while (0)
 
-/* TEST_CALIBRATION() - This macro is used to calculate the number of
+/**
+ * TEST_CALIBRATION() - This macro is used to calculate the number of
  * repetitions needed for execution of a test routine, so that the total
  * duration is long enough to be measured by a timer with millisecond
  * resolution like gettimeofday().
@@ -267,8 +268,8 @@ tabort_handler (bool   set_values,
  * of inner loop repetitions needed for benchmarking a piece of code.
  * Estimated run time: the calibration process should take somewhat
  * less than MIN (max_calibration_time, (target_ms * 2 * 7)) milliseconds.
- * @arg target_ms       expected total test runtime for RUNS * dups * testfunc_time
- * @var max_calibration_time expected upper bound for test calibration runtime
+ * @li @c target_ms            expected total test runtime for RUNS * dups * testfunc_time
+ * @li @c max_calibration_time expected upper bound for test calibration runtime
  * In this macro, "dups" is calculated appropriately for max_calibration_time,
  * and scaled upon return to match target_ms accordingly.
  */
diff --git a/birnet/birnetthreadimpl.cc b/birnet/birnetthreadimpl.cc
index 62036fa..957a361 100644
--- a/birnet/birnetthreadimpl.cc
+++ b/birnet/birnetthreadimpl.cc
@@ -273,7 +273,7 @@ birnet_thread_exec (gpointer data)
   global_startup_mutex.lock();
   /* acquiring this mutex waits for birnet_thread_run() to figure inlist (global_thread_list, self) */
   global_startup_mutex.unlock();
-  
+
   func (user_data);
   g_datalist_clear (&thread->qdata);
 
@@ -298,7 +298,7 @@ common_thread_start (BirnetThread    *thread,
 {
   GThread *gthread = NULL;
   GError *gerror = NULL;
-  
+
   g_return_val_if_fail (thread != NULL, FALSE);
   g_return_val_if_fail (thread->tid == -1, FALSE);
   g_return_val_if_fail (func != NULL, FALSE);
@@ -1148,17 +1148,17 @@ birnet_guard_deregister_all (BirnetThread *thread)
  * http://research.sun.com/scalable/Papers/CATS2003.pdf and
  * http://www.research.ibm.com/people/m/michael/ieeetpds-2004.pdf.
  * The exact sequence of steps to protect and access a node is as follows:
- * @* 1) Store the adress of a node to be protected in a hazard pointer
- * @* 2) Verify that the hazard pointer points to a valid node
- * @* 3) Dereference the node only as long as it's protected by the hazard pointer.
- * @* For example:
- * @* 0: BirnetGuard *guard = birnet_guard_register (1);
- * @* 1: peek_head_label:
- * @* 2: auto GSList *node = shared_list_head;
- * @* 3: birnet_guard_protect (guard, 0, node);
- * @* 4: if (node != shared_list_head) goto peek_head_label;
- * @* 5: operate_on_protected_node (node);
- * @* 6: birnet_guard_deregister (guard);
+ * @li 1) Store the adress of a node to be protected in a hazard pointer
+ * @li 2) Verify that the hazard pointer points to a valid node
+ * @li 3) Dereference the node only as long as it's protected by the hazard pointer.
+ * For example:
+ * @li @c 0: BirnetGuard *guard = birnet_guard_register (1);
+ * @li @c 1: peek_head_label:
+ * @li @c 2: auto GSList *node = shared_list_head;
+ * @li @c 3: birnet_guard_protect (guard, 0, node);
+ * @li @c 4: if (node != shared_list_head) goto peek_head_label;
+ * @li @c 5: operate_on_protected_node (node);
+ * @li @c 6: birnet_guard_deregister (guard);
  */
 #if 0
 static inline
diff --git a/birnet/birnetutils.cc b/birnet/birnetutils.cc
index 6a45bda..529b336 100644
--- a/birnet/birnetutils.cc
+++ b/birnet/birnetutils.cc
@@ -646,6 +646,10 @@ string_cmp_uuid (const String &uuid_string1,
 }
 
 /* --- file utils --- */
+/**
+ * @namespace Birnet::Path
+ * The Birnet::Path namespace covers function for file path manipulation and evaluation.
+ */
 namespace Path {
 
 const String
@@ -787,19 +791,17 @@ errno_check_file (const char *file_name,
  * Perform various checks on @a file and return whether all
  * checks passed. On failure, errno is set appropriately, and
  * FALSE is returned. Available features to be checked for are:
- * @itemize
- * @item e - @a file must exist
- * @item r - @a file must be readable
- * @item w - @a file must be writable
- * @item x - @a file must be executable
- * @item f - @a file must be a regular file
- * @item d - @a file must be a directory
- * @item l - @a file must be a symbolic link
- * @item c - @a file must be a character device
- * @item b - @a file must be a block device
- * @item p - @a file must be a named pipe
- * @item s - @a file must be a socket.
- * @done
+ * @li @c e - @a file must exist
+ * @li @c r - @a file must be readable
+ * @li @c w - @a file must be writable
+ * @li @c x - @a file must be executable
+ * @li @c f - @a file must be a regular file
+ * @li @c d - @a file must be a directory
+ * @li @c l - @a file must be a symbolic link
+ * @li @c c - @a file must be a character device
+ * @li @c b - @a file must be a block device
+ * @li @c p - @a file must be a named pipe
+ * @li @c s - @a file must be a socket.
  */
 bool
 check (const String &file,