Cleanup doxygen style.
authorMatthias Bolte <matthias.bolte@googlemail.com>
Sat, 25 Apr 2009 12:44:20 +0000 (14:44 +0200)
committerMatthias Bolte <matthias.bolte@googlemail.com>
Sat, 25 Apr 2009 12:44:20 +0000 (14:44 +0200)
Signed-off-by: Matthias Bolte <matthias.bolte@googlemail.com>

34 files changed:
Doxyfile
HACKING
backend/data/data.h
backend/data/file/data.c
backend/mutex/mutex.h
backend/mutex/none/mutex.c
backend/mutex/pthread/mutex.c
backend/network/common/common.c
backend/network/common/common.h
backend/network/dhcponly/network.c
backend/network/network.h
include/libvscmgmt/checkpoint.h
include/libvscmgmt/core.h
include/libvscmgmt/host.h
include/libvscmgmt/ipv4.h
include/libvscmgmt/libvscmgmt.h
include/libvscmgmt/network.h
include/libvscmgmt/suspension.h
include/libvscmgmt/types.h
include/libvscmgmt/uuid.h
include/libvscmgmt/vm.h
lib/core.c
lib/host.c
lib/host.h
utils/host.c
utils/host.h
utils/ipv4.c
utils/ipv4.h
utils/mac.c
utils/mac.h
utils/network.c
utils/network.h
utils/types.h
utils/uuid.c

index 60d87d1..15e2f81 100644 (file)
--- a/Doxyfile
+++ b/Doxyfile
@@ -137,7 +137,7 @@ SHORT_NAMES            = NO
 # comments will behave just like regular Qt-style comments
 # (thus requiring an explicit @brief command for a brief description.)
 
-JAVADOC_AUTOBRIEF      = YES
+JAVADOC_AUTOBRIEF      = NO
 
 # If the QT_AUTOBRIEF tag is set to YES then Doxygen will
 # interpret the first line (until the first dot) of a Qt-style
@@ -186,7 +186,7 @@ ALIASES                =
 # For instance, some of the names that are used will be different. The list
 # of all members will be omitted, etc.
 
-OPTIMIZE_OUTPUT_FOR_C  = NO
+OPTIMIZE_OUTPUT_FOR_C  = YES
 
 # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java
 # sources only. Doxygen will then generate output that is more tailored for
@@ -302,12 +302,12 @@ EXTRACT_ALL            = YES
 # If the EXTRACT_PRIVATE tag is set to YES all private members of a class
 # will be included in the documentation.
 
-EXTRACT_PRIVATE        = NO
+EXTRACT_PRIVATE        = YES
 
 # If the EXTRACT_STATIC tag is set to YES all static members of a file
 # will be included in the documentation.
 
-EXTRACT_STATIC         = NO
+EXTRACT_STATIC         = YES
 
 # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs)
 # defined locally in source files will be included in the documentation.
@@ -320,7 +320,7 @@ EXTRACT_LOCAL_CLASSES  = YES
 # the interface are included in the documentation.
 # If set to NO (the default) only methods in the interface are included.
 
-EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_LOCAL_METHODS  = YES
 
 # If this flag is set to YES, the members of anonymous namespaces will be
 # extracted and appear in the documentation as a namespace called
@@ -364,7 +364,7 @@ HIDE_IN_BODY_DOCS      = NO
 # to NO (the default) then the documentation will be excluded.
 # Set it to YES to include the internal documentation.
 
-INTERNAL_DOCS          = NO
+INTERNAL_DOCS          = YES
 
 # If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate
 # file names in lower-case letters. If set to YES upper-case letters are also
@@ -470,13 +470,13 @@ SHOW_USED_FILES        = YES
 # then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy
 # in the documentation. The default is NO.
 
-SHOW_DIRECTORIES       = NO
+SHOW_DIRECTORIES       = YES
 
 # Set the SHOW_FILES tag to NO to disable the generation of the Files page.
 # This will remove the Files entry from the Quick Index and from the
 # Folder Tree View (if specified). The default is YES.
 
-SHOW_FILES             = NO
+SHOW_FILES             = YES
 
 # Set the SHOW_NAMESPACES tag to NO to disable the generation of the
 # Namespaces page.
@@ -564,7 +564,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = backend cli lib utils
+INPUT                  = backend cli include lib utils
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@@ -1227,7 +1227,7 @@ SEARCH_INCLUDES        = YES
 # contain include files that are not input files but should be processed by
 # the preprocessor.
 
-INCLUDE_PATH           =
+INCLUDE_PATH           = include
 
 # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
 # patterns (like *.h and *.hpp) to filter out the header-files in the
diff --git a/HACKING b/HACKING
index ba72010..e302147 100644 (file)
--- a/HACKING
+++ b/HACKING
@@ -33,3 +33,18 @@ XML-RPC
   reported via the code/message/value system described before
 - ...
 
+DOXYGEN
+
+- if a function has a prototype in a header file and the implementation in a
+  source file then document it in the source file only
+- if the function defines an interface like the interface for the backends
+  (that may have various implementations) put the documentation of the expected
+  functionality of the function in the header that defines the interface and
+  put the documentation about the actual implementation in the source files
+  that implement this interface
+- if an enum or macro is defined only in a header file document it there
+- use the /*! ... style, not the /** ... style
+- use the @brief style, not the \brief style
+- mark the brief line explicitly with @brief
+- mark internal functions and types with @internal
+- ...
index 074f453..a8571c0 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__BACKEND__DATA_H__
 #define __VSC_MGMT__BACKEND__DATA_H__
 
 #include "../../include/libvscmgmt/types.h"
 
-/**
+/*!
+ * @brief
+ * @internal
  *
- * Function is not threadsafe.
+ * @note Function is not threadsafe.
  */
 void
 _vsc_mgmt_data_init (struct VscError *error, const char *config);
 
-/**
+/*!
+ * @brief
+ * @internal
  *
- * Function is not threadsafe.
+ * @note Function is not threadsafe.
  */
 void
 _vsc_mgmt_data_cleanup (void);
@@ -43,48 +51,60 @@ _vsc_mgmt_data_lock (void);
 void
 _vsc_mgmt_data_unlock (void);
 
-/**
+/*!
+ * @brief
+ * @internal
  *
- * Caller must lock the data mutex before calling.
+ * @note Caller must lock the data mutex before calling.
  */
 void
 _vsc_mgmt_data_backup (struct VscError *error);
 
-/**
+/*!
+ * @brief
+ * @internal
  *
- * Caller must lock the data mutex before calling.
+ * @note Caller must lock the data mutex before calling.
  */
 void
 _vsc_mgmt_data_recover (struct VscError *error);
 
-/**
+/*!
+ * @brief
+ * @internal
  *
- * Caller must lock the data mutex before calling.
+ * @note Caller must lock the data mutex before calling.
  */
 void
 _vsc_mgmt_data_host_add (struct VscError *error,
                          const struct VscMgmtHostInfo *host_info);
 
-/**
+/*!
+ * @brief
+ * @internal
  *
- * Caller must lock the data mutex before calling.
+ * @note Caller must lock the data mutex before calling.
  */
 void
 _vsc_mgmt_data_host_remove (struct VscError *error,
                             const struct VscMgmtIpv4 *host_ipv4);
 
-/**
+/*!
+ * @brief
+ * @internal
  *
- * Caller must lock the data mutex before calling.
+ * @note Caller must lock the data mutex before calling.
  */
 void
 _vsc_mgmt_data_host_get_info (struct VscError *error,
                               const struct VscMgmtIpv4 *host_ipv4,
                               struct VscMgmtHostInfo *host_info);
 
-/**
+/*!
+ * @brief
+ * @internal
  *
- * Caller must lock the data mutex before calling.
+ * @note Caller must lock the data mutex before calling.
  */
 struct VscMgmtIpv4 * /* host_ipv4_list */
 _vsc_mgmt_data_host_get_list (struct VscError *error);
index c4a71b6..6e95c6c 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #include <libvscmisc/assert.h>
 #include <libvscmisc/error.h>
 #include <libvscmisc/memory.h>
@@ -36,6 +40,12 @@ static struct VscMgmtMutex *_data_mutex = NULL;
  */
 static struct VscMgmtHostInfo *_data_host_info_list = NULL;
 
+/*!
+ * @brief
+ * @internal
+ *
+ * @note Function is not threadsafe.
+ */
 void
 _vsc_mgmt_data_init (struct VscError *error, const char *config)
 {
@@ -71,6 +81,12 @@ failure:
        _vsc_mgmt_mutex_free (&_data_mutex);
 }
 
+/*!
+ * @brief
+ * @internal
+ *
+ * @note Function is not threadsafe.
+ */
 void
 _vsc_mgmt_data_cleanup (void)
 {
@@ -99,6 +115,12 @@ _vsc_mgmt_data_unlock (void)
        _vsc_mgmt_mutex_unlock (_data_mutex);
 }
 
+/*!
+ * @brief
+ * @internal
+ *
+ * @note Caller must lock the data mutex before calling.
+ */
 void
 _vsc_mgmt_data_backup (struct VscError *error)
 {
@@ -108,6 +130,12 @@ _vsc_mgmt_data_backup (struct VscError *error)
        VSC__ERROR0 (error, VSC__ERROR_CODE__NOT_IMPLEMENTED_YET);
 }
 
+/*!
+ * @brief
+ * @internal
+ *
+ * @note Caller must lock the data mutex before calling.
+ */
 void
 _vsc_mgmt_data_recover (struct VscError *error)
 {
@@ -117,6 +145,12 @@ _vsc_mgmt_data_recover (struct VscError *error)
        VSC__ERROR0 (error, VSC__ERROR_CODE__NOT_IMPLEMENTED_YET);
 }
 
+/*!
+ * @brief
+ * @internal
+ *
+ * @note Caller must lock the data mutex before calling.
+ */
 void
 _vsc_mgmt_data_host_add (struct VscError *error,
                          const struct VscMgmtHostInfo *host_info)
@@ -141,6 +175,12 @@ _vsc_mgmt_data_host_add (struct VscError *error,
        }
 }
 
+/*!
+ * @brief
+ * @internal
+ *
+ * @note Caller must lock the data mutex before calling.
+ */
 void
 _vsc_mgmt_data_host_remove (struct VscError *error,
                             const struct VscMgmtIpv4 *host_ipv4)
@@ -163,6 +203,12 @@ _vsc_mgmt_data_host_remove (struct VscError *error,
        _vsc_mgmt_host_info_list_remove (&_data_host_info_list, host_info);
 }
 
+/*!
+ * @brief
+ * @internal
+ *
+ * @note Caller must lock the data mutex before calling.
+ */
 void
 _vsc_mgmt_data_host_get_info (struct VscError *error,
                               const struct VscMgmtIpv4 *host_ipv4 VSC__ATTR__UNUSED,
@@ -176,6 +222,12 @@ _vsc_mgmt_data_host_get_info (struct VscError *error,
        VSC__ERROR0 (error, VSC__ERROR_CODE__NOT_IMPLEMENTED_YET);
 }
 
+/*!
+ * @brief
+ * @internal
+ *
+ * @note Caller must lock the data mutex before calling.
+ */
 struct VscMgmtIpv4 * /* host_ipv4_list */
 _vsc_mgmt_data_host_get_list (struct VscError *error)
 {
index cb349ab..ab944b8 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__BACKEND__MUTEX_H__
 #define __VSC_MGMT__BACKEND__MUTEX_H__
 
 #include "../../include/libvscmgmt/types.h"
 #include "../../utils/types.h"
 
-/**
- * Allocates and initializes an initially unlocked mutex and returns it.
+/*!
+ * @brief Allocates and initializes an initially unlocked mutex and returns it.
+ * @internal
  */
 struct VscMgmtMutex * /* mutex */
 _vsc_mgmt_mutex_new (struct VscError *error);
 
-/**
- * Allocates and initializes an initially unlocked, recursive mutex and
- * returns it.
+/*!
+ * @brief Allocates and initializes an initially unlocked, recursive mutex and
+ *        returns it.
+ * @internal
  */
 struct VscMgmtMutex * /* mutex */
 _vsc_mgmt_mutex_new_recursive (struct VscError *error);
 
-/**
- * Cleans up a mutex and frees its memory.
+/*!
+ * @brief Cleans up a mutex and frees its memory.
+ * @internal
  */
 void
 _vsc_mgmt_mutex_free (struct VscMgmtMutex **mutex);
index d71de92..54dadd8 100644 (file)
@@ -30,8 +30,9 @@ struct VscMgmtMutex {
     int nothing;
 };
 
-/**
- * Allocates and initializes an initially unlocked mutex and returns it.
+/*!
+ * @brief Allocates and initializes an initially unlocked mutex and returns it.
+ * @internal
  */
 struct VscMgmtMutex * /* mutex */
 _vsc_mgmt_mutex_new (struct VscError *error)
@@ -51,9 +52,10 @@ _vsc_mgmt_mutex_new (struct VscError *error)
        return mutex;
 }
 
-/**
- * Allocates and initializes an initially unlocked, recursive mutex and
- * returns it.
+/*!
+ * @brief Allocates and initializes an initially unlocked, recursive mutex and
+ *        returns it.
+ * @internal
  */
 struct VscMgmtMutex * /* mutex */
 _vsc_mgmt_mutex_new_recursive (struct VscError *error)
@@ -73,8 +75,9 @@ _vsc_mgmt_mutex_new_recursive (struct VscError *error)
        return mutex;
 }
 
-/**
- * Cleans up a mutex and frees its memory.
+/*!
+ * @brief ACleans up a mutex and frees its memory.
+ * @internal
  */
 void
 _vsc_mgmt_mutex_free (struct VscMgmtMutex **mutex)
index a86f4fa..b6de98c 100644 (file)
@@ -34,8 +34,9 @@ struct VscMgmtMutex {
        pthread_mutex_t handle;
 };
 
-/**
- * Allocates and initializes an initially unlocked mutex and returns it.
+/*!
+ * @brief Allocates and initializes an initially unlocked mutex and returns it.
+ * @internal
  */
 struct VscMgmtMutex * /* mutex */
 _vsc_mgmt_mutex_new (struct VscError *error)
@@ -70,9 +71,10 @@ failure:
        return NULL;
 }
 
-/**
- * Allocates and initializes an initially unlocked, recursive mutex and
- * returns it.
+/*!
+ * @brief Allocates and initializes an initially unlocked, recursive mutex and
+ *        returns it.
+ * @internal
  */
 struct VscMgmtMutex * /* mutex */
 _vsc_mgmt_mutex_new_recursive (struct VscError *error)
@@ -113,8 +115,9 @@ failure:
        return NULL;
 }
 
-/**
- * Cleans up a mutex and frees its memory.
+/*!
+ * @brief Cleans up a mutex and frees its memory.
+ * @internal
  */
 void
 _vsc_mgmt_mutex_free (struct VscMgmtMutex **mutex)
index a8a2907..578d5ef 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #include <libvscmisc/assert.h>
 #include <libvscmisc/error.h>
 
@@ -140,9 +144,10 @@ _vsc_mgmt_network_common_use_ipv4 (struct VscError *error,
 }
 
 
-/**
- * Release the previously fetched IPv4 address from the given network to the
- * pool of free IPs of this network.
+/*!
+ * @brief Release the previously fetched IPv4 address from the given network
+ *        to the pool of free IPs of this network.
+ * @internal
  */
 void
 _vsc_mgmt_network_common_release_ipv4 (struct VscError *error,
index c9628a1..ebec775 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__BACKEND__COMMON_H__
 #define __VSC_MGMT__BACKEND__COMMON_H__
 
index 48f4b34..cab4507 100644 (file)
@@ -1,5 +1,6 @@
 /*
- * dhcponly.c: DHCP only based network backend for Virtualized Supercomputer Management
+ * dhcponly.c: DHCP only based network backend for Virtualized Supercomputer
+ *             Management
  *
  * Copyright (C) 2009 Matthias Bolte <matthias.bolte@googlemail.com>
  * Copyright (C) 2009 Maximilian Wilhelm <max@rfc2324.org>
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #include <libvscmisc/assert.h>
 #include <libvscmisc/error.h>
 
index 89f40ca..2be25ac 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__BACKEND__NETWORK_H__
 #define __VSC_MGMT__BACKEND__NETWORK_H__
 
index 9c2dce4..b051b82 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__CHECKPOINT_H__
 #define __VSC_MGMT__CHECKPOINT_H__
 
index 208c161..67cdcf8 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__CORE_H__
 #define __VSC_MGMT__CORE_H__
 
 extern "C" {
 #endif
 
-/**
- *
- * Function is not threadsafe.
- */
 void
 vsc_mgmt_init (struct VscError *error);
 
-/**
- *
- * Function is not threadsafe.
- */
 void
 vsc_mgmt_cleanup (void);
 
index b6cdc00..7a39ca8 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__HOST_H__
 #define __VSC_MGMT__HOST_H__
 
@@ -39,38 +43,17 @@ vsc_mgmt_host_get_info (struct VscError *error,
                         const struct VscMgmtIpv4 *host_ipv4,
                         struct VscMgmtHostInfo *host_info);
 
-/**
- * Returns a UUID list representing all virtual machines currently available
- * on the host.
- *
- * The list must be freed by the caller via the vsc_mgmt_uuid_list_free
- * function.
- */
 struct VscMgmtUuid * /* vm_uuid_list */
 vsc_mgmt_host_get_vm_list (struct VscError *error,
                            const struct VscMgmtIpv4 *host_ipv4);
 
-/**
- * Returns an IPv4 list representing all currently known host.
- *
- * The list must be freed by the caller via the vsc_mgmt_ipv4_list_free
- * function.
- */
 struct VscMgmtIpv4 * /* host_ipv4_list */
 vsc_mgmt_host_get_list (struct VscError *error);
 
-/**
- * Parses a host type from its string representation and returns it.
- */
 enum VscMgmtHostType /* host_type */
 vsc_mgmt_host_type_parse (struct VscError *error,
                           const char *host_type_string);
 
-/**
- * Returns the string representaion of the host type.
- *
- * The string must not be freed by the caller.
- */
 const char * /* host_type_string */
 vsc_mgmt_host_type_string (enum VscMgmtHostType host_type);
 
index 62f41a1..9068a1a 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__IPV4_H__
 #define __VSC_MGMT__IPV4_H__
 
 extern "C" {
 #endif
 
-/**
- * Parses an IPv4 from its string representation.
- */
 void
 vsc_mgmt_ipv4_parse (struct VscError *error, const char *ipv4_string,
                      struct VscMgmtIpv4 *ipv4);
 
-/**
- * Formats an IPv4 to its string representation.
- *
- * The caller must ensure that the string buffer can at least hold
- * VSC_MGMT__IPV4__STRING_SIZE bytes.
- */
 void
 vsc_mgmt_ipv4_format (const struct VscMgmtIpv4 *ipv4, char *ipv4_string);
 
-/**
- * Appends a duplicate of the IPv4 to the list.
- *
- * If an error occurs then the list is still untouched.
- */
 void
 vsc_mgmt_ipv4_list_append (struct VscError *error,
                            struct VscMgmtIpv4 **ipv4_list,
                            const struct VscMgmtIpv4 *ipv4);
 
-/**
- * Recursively frees the IPv4 list.
- */
 void
 vsc_mgmt_ipv4_list_free (struct VscMgmtIpv4 **ipv4_list);
 
index de4dbd3..ddf5477 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT_H__
 #define __VSC_MGMT_H__
 
index b9549f6..59f80d0 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__NETWORK_H__
 #define __VSC_MGMT__NETWORK_H__
 
@@ -37,19 +41,11 @@ void
 vsc_mgmt_network_teardown (struct VscError *error,
                            const struct VscMgmtUuid *network_uuid);
 
-/**
- * Appends a duplicate of the network to the list.
- *
- * If an error occurs then the list is still untouched.
- */
 void
 vsc_mgmt_network_list_append (struct VscError *error,
                               struct VscMgmtNetwork **network_list,
                               const struct VscMgmtNetwork *network);
 
-/**
- * Recursively frees the network list.
- */
 void
 vsc_mgmt_network_list_free (struct VscMgmtNetwork **network_list);
 
index 095610d..84d04af 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__SUSPENSION_H__
 #define __VSC_MGMT__SUSPENSION_H__
 
index b7bc2a1..bd14d4c 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__TYPES_H__
 #define __VSC_MGMT__TYPES_H__
 
index 158582e..4428200 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__UUID_H__
 #define __VSC_MGMT__UUID_H__
 
 extern "C" {
 #endif
 
-/**
- * Parses a UUID from its string representation.
- */
 void
 vsc_mgmt_uuid_parse (struct VscError *error, const char *uuid_string,
                      struct VscMgmtUuid *uuid);
 
-/**
- * Formats a UUID to its string representation.
- *
- * The caller must ensure that the string buffer can at least hold
- * VSC_MGMT__UUID__STRING_SIZE bytes.
- */
 void
 vsc_mgmt_uuid_format (const struct VscMgmtUuid *uuid, char *uuid_string);
 
-/**
- * Appends a duplicate of the UUID to the list.
- *
- * If an error occurs then the list is still untouched.
- */
 void
 vsc_mgmt_uuid_list_append (struct VscError *error,
                            struct VscMgmtUuid **uuid_list,
                            const struct VscMgmtUuid *uuid);
 
-/**
- * Recursively frees the UUID list.
- */
 void
 vsc_mgmt_uuid_list_free (struct VscMgmtUuid **uuid_list);
 
index cfabc46..249eeff 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__VM_H__
 #define __VSC_MGMT__VM_H__
 
index d14b3d4..86b01e6 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #include <libvirt/libvirt.h>
 
 #include <libvscmisc/assert.h>
 
 static int _initialized = FALSE;
 
-/**
+/*!
+ * @brief
  *
- * Function is not threadsafe.
+ * @note Function is not threadsafe.
  */
 void
 vsc_mgmt_init (struct VscError *error)
@@ -70,9 +75,10 @@ vsc_mgmt_init (struct VscError *error)
        _initialized = TRUE;
 }
 
-/**
+/*!
+ * @brief
  *
- * Function is not threadsafe.
+ * @note Function is not threadsafe.
  */
 void
 vsc_mgmt_cleanup (void)
index d0ba6d5..42de318 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #include <string.h>
 
 #include <libvirt/libvirt.h>
@@ -304,9 +308,9 @@ vsc_mgmt_host_get_info (struct VscError *error,
        VSC__ERROR0 (error, VSC__ERROR_CODE__NOT_IMPLEMENTED_YET);
 }
 
-/**
- * Returns a UUID list representing all virtual machines currently available
- * on the host.
+/*!
+ * @brief Returns a UUID list representing all virtual machines currently
+ * available on the host.
  *
  * The list must be freed by the caller via the vsc_mgmt_uuid_list_free
  * function.
@@ -324,8 +328,9 @@ vsc_mgmt_host_get_vm_list (struct VscError *error,
        return NULL;
 }
 
-/**
- * Returns a connection to the host.
+/*!
+ * @brief Returns a connection to the host.
+ * @internal
  *
  * If there is already a connnection to this host opened the refcount of the
  * existing connection is increased and the existing connection is returned,
@@ -333,7 +338,7 @@ vsc_mgmt_host_get_vm_list (struct VscError *error,
  * In both cases the _vsc_mgmt_host_disconnect function must be called for
  * each successful call to the _vsc_mgmt_host_connect function.
  *
- * Caller must lock the data mutex before calling.
+ * @note Caller must lock the data mutex before calling.
  */
 virConnectPtr
 _vsc_mgmt_host_connect (struct VscError *error,
@@ -430,12 +435,13 @@ failure:
        return NULL;
 }
 
-/**
- * Decreases the refcount for the connection to this host.
+/*!
+ * @brief Decreases the refcount for the connection to this host.
+ * @internal
  *
  * If the refcount drops to zero the connection will be closed.
  *
- * Caller must lock the data mutex before calling.
+ * @note Caller must lock the data mutex before calling.
  */
 void
 _vsc_mgmt_host_disconnect (struct VscError *error,
index 6a3e7fd..5ad3864 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__LIB__HOST_H__
 #define __VSC_MGMT__LIB__HOST_H__
 
 
 #include "../include/libvscmgmt/types.h"
 
-/**
- * Returns a connection to the host.
- *
- * If there is already a connnection to this host opened the refcount of the
- * existing connection is increased and the existing connection is returned,
- * otherwise a new connection is opened.
- * In both cases the _vsc_mgmt_host_disconnect function must be called for
- * each successful call to the _vsc_mgmt_host_connect function.
- *
- * Caller must lock the data mutex before calling.
- */
 virConnectPtr
 _vsc_mgmt_host_connect (struct VscError *error,
                         const struct VscMgmtHostInfo *host_info);
 
-/**
- * Decreases the refcount for the connection to this host.
- *
- * If the refcount drops to zero the connection will be closed.
- *
- * Caller must lock the data mutex before calling.
- */
 void
 _vsc_mgmt_host_disconnect (struct VscError *error,
                            const struct VscMgmtIpv4 *host_ipv4);
index 8ddbb29..ac789d5 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #include <strings.h>
 
 #include <libvscmisc/assert.h>
@@ -37,8 +41,8 @@ _host_info_match (struct VscList *item, void *match_data)
        return _vsc_mgmt_ipv4_compare (&host_info->host_ipv4, host_ipv4) == 0;
 }
 
-/**
- * Parses a host type from its string representation and returns it.
+/*!
+ * @brief Parses a host type from its string representation and returns it.
  */
 enum VscMgmtHostType
 vsc_mgmt_host_type_parse (struct VscError *error,
@@ -65,8 +69,8 @@ vsc_mgmt_host_type_parse (struct VscError *error,
        return VSC_MGMT__HOST_TYPE__UNDEFINED;
 }
 
-/**
- * Returns the string representaion of the host type.
+/*!
+ * @brief Returns the string representaion of the host type.
  *
  * The string must not be freed by the caller.
  */
@@ -188,8 +192,9 @@ _vsc_mgmt_host_info_is_valid (const struct VscMgmtHostInfo *host_info)
        return TRUE;
 }
 
-/**
- * Appends a duplicate of the host info to the list.
+/*!
+ * @brief Appends a duplicate of the host info to the list.
+ * @internal
  *
  * If an error occurs then the list is untouched.
  */
@@ -212,11 +217,13 @@ _vsc_mgmt_host_info_list_append (struct VscError *error,
        }
 }
 
-/**
- * Looks up an host info in the list.
+/*!
+ * @brief Looks up an host info in the list.
+ * @internal
  *
  * The first host info that the matchs the IPv4 is returned. If no match occurs
  * NULL is returned.
+ *
  */
 struct VscMgmtHostInfo * /* host_info */
 _vsc_mgmt_host_info_list_lookup (const struct VscMgmtHostInfo *host_info_list,
@@ -231,8 +238,9 @@ _vsc_mgmt_host_info_list_lookup (const struct VscMgmtHostInfo *host_info_list,
                    (void *) host_ipv4);
 }
 
-/**
- * Removes the host info from the list and frees it.
+/*!
+ * @brief Removes the host info from the list and frees it.
+ * @internal
  *
  * If the host info is not in the list then the list is untouched.
  */
@@ -248,8 +256,9 @@ _vsc_mgmt_host_info_list_remove (struct VscMgmtHostInfo **host_info_list,
                         (VscList_FreeFunction) _vsc_mgmt_host_info_free);
 }
 
-/**
- * Recursively frees the host info list.
+/*!
+ * @brief Recursively frees the host info list.
+ * @internal
  */
 void
 _vsc_mgmt_host_info_list_free (struct VscMgmtHostInfo **host_info_list)
index cb169b1..b297d19 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__UTILS__HOST_H__
 #define __VSC_MGMT__UTILS__HOST_H__
 
@@ -36,38 +40,19 @@ _vsc_mgmt_host_info_free (struct VscMgmtHostInfo **host_info);
 int /* is_valid */
 _vsc_mgmt_host_info_is_valid (const struct VscMgmtHostInfo *host_info);
 
-/**
- * Appends a duplicate of the host info to the list.
- *
- * If an error occurs then the list is untouched.
- */
 void
 _vsc_mgmt_host_info_list_append (struct VscError *error,
                                  struct VscMgmtHostInfo **host_info_list,
                                  const struct VscMgmtHostInfo *host_info);
 
-/**
- * Looks up an host info in the list.
- *
- * The first host info that the matchs the IPv4 is returned. If no match occurs
- * NULL is returned.
- */
 struct VscMgmtHostInfo * /* host_info */
 _vsc_mgmt_host_info_list_lookup (const struct VscMgmtHostInfo *host_info_list,
                                  const struct VscMgmtIpv4 *host_ipv4);
 
-/**
- * Removes the host info from the list and frees it.
- *
- * If the host info is not in the list then the list is untouched.
- */
 void
 _vsc_mgmt_host_info_list_remove (struct VscMgmtHostInfo **host_info_list,
                                  struct VscMgmtHostInfo *host_info);
 
-/**
- * Recursively frees the host info list.
- */
 void
 _vsc_mgmt_host_info_list_free (struct VscMgmtHostInfo **host_info_list);
 
index f252293..d9c0b2e 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #include <memory.h>
 
 #include <libvscmisc/assert.h>
@@ -28,8 +32,8 @@
 
 #include "utils.h"
 
-/**
- * Parses an IPv4 from its string representation.
+/*!
+ * @brief Parses an IPv4 from its string representation.
  */
 void
 vsc_mgmt_ipv4_parse (struct VscError *error, const char *ipv4_string,
@@ -93,8 +97,8 @@ vsc_mgmt_ipv4_parse (struct VscError *error, const char *ipv4_string,
        }
 }
 
-/**
- * Formats an IPv4 to its string representation.
+/*!
+ * @brief Formats an IPv4 to its string representation.
  *
  * The caller must ensure that the string buffer can at least hold
  * VSC_MGMT__IPV4__STRING_SIZE bytes.
@@ -109,8 +113,8 @@ vsc_mgmt_ipv4_format (const struct VscMgmtIpv4 *ipv4, char *ipv4_string)
                  ipv4->bytes[0], ipv4->bytes[1], ipv4->bytes[2], ipv4->bytes[3]);
 }
 
-/**
- * Appends a duplicate of the IPv4 to the list.
+/*!
+ * @brief Appends a duplicate of the IPv4 to the list.
  *
  * If an error occurs then the list is untouched.
  */
@@ -134,8 +138,8 @@ vsc_mgmt_ipv4_list_append (struct VscError *error,
        }
 }
 
-/**
- * Recursively frees the IPv4 list.
+/*!
+ * @brief Recursively frees the IPv4 list.
  */
 void
 vsc_mgmt_ipv4_list_free (struct VscMgmtIpv4 **ipv4_list)
index 9a0ef8b..e3180d1 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__UTILS__IPV4_H__
 #define __VSC_MGMT__UTILS__IPV4_H__
 
index 85d5c34..cda5d49 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #include <stdio.h>
 
 #include <libvscmisc/assert.h>
 
 #include "utils.h"
 
-/**
- * Formats a MAC address to its string representation.
+/*!
+ * @brief Formats a MAC address to its string representation.
+ * @internal
  *
  * The caller must ensure that the string buffer can at least hold
  * VSC_MGMT__MAC__STRING_SIZE bytes.
index db87d56..22c801e 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__UTILS__MAC_H__
 #define __VSC_MGMT__UTILS__MAC_H__
 
 #include "types.h"
 
-/**
- * Formats a MAC address to its string representation.
- *
- * The caller must ensure that the string buffer can at least hold
- * VSC_MGMT__MAC__STRING_SIZE bytes.
- */
 void _vsc_mgmt_mac_format (const struct VscMgmtMac *mac, char *mac_string);
 
 #endif /* __VSC_MGMT__UTILS__MAC_H__ */
index db52380..a05b334 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #include <libvscmisc/assert.h>
 #include <libvscmisc/error.h>
 #include <libvscmisc/list.h>
@@ -25,8 +29,8 @@
 
 #include "utils.h"
 
-/**
- * Appends a duplicate of the network to the list.
+/*!
+ * @brief Appends a duplicate of the network to the list.
  *
  * If an error occurs then the list is untouched.
  */
@@ -51,8 +55,8 @@ vsc_mgmt_network_list_append (struct VscError *error,
        }
 }
 
-/**
- * Recursively frees the network list.
+/*!
+ * @brief Recursively frees the network list.
  */
 void
 vsc_mgmt_network_list_free (struct VscMgmtNetwork **network_list)
index fa089dc..0784520 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__UTILS__NETWORK_H__
 #define __VSC_MGMT__UTILS__NETWORK_H__
 
index c863383..767d6bb 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MGMT__UTILS__TYPES_H__
 #define __VSC_MGMT__UTILS__TYPES_H__
 
index d1882cb..495eb94 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #include <uuid.h>
 
 #include <libvscmisc/assert.h>
@@ -27,8 +31,8 @@
 
 #include "utils.h"
 
-/**
- * Parses a UUID from string representation.
+/*!
+ * @brief Parses a UUID from string representation.
  */
 void
 vsc_mgmt_uuid_parse (struct VscError *error, const char *uuid_string,
@@ -43,8 +47,8 @@ vsc_mgmt_uuid_parse (struct VscError *error, const char *uuid_string,
        }
 }
 
-/**
- * Formats a UUID to string representation.
+/*!
+ * @brief Formats a UUID to string representation.
  *
  * The caller must ensure that the string buffer can at least hold
  * VSC_MGMT__UUID__STRING_SIZE bytes.
@@ -58,8 +62,8 @@ vsc_mgmt_uuid_format (const struct VscMgmtUuid *uuid, char *uuid_string)
        uuid_unparse_lower (uuid->bytes, uuid_string);
 }
 
-/**
- * Appends a duplicate of the UUID to the list.
+/*!
+ * @brief Appends a duplicate of the UUID to the list.
  *
  * If an error occurs then the list is untouched.
  */
@@ -83,8 +87,8 @@ vsc_mgmt_uuid_list_append (struct VscError *error,
        }
 }
 
-/**
- * Recursively frees the UUID list.
+/*!
+ * @brief Recursively frees the UUID list.
  */
 void
 vsc_mgmt_uuid_list_free (struct VscMgmtUuid **uuid_list)