First shot on code documentation with Doxygen.
authorMaximilian Wilhelm <max@rfc2324.org>
Sat, 28 Nov 2009 07:07:49 +0000 (08:07 +0100)
committerMaximilian Wilhelm <max@rfc2324.org>
Sat, 28 Nov 2009 07:07:49 +0000 (08:07 +0100)
Signed-off-by: Maximilian Wilhelm <max@rfc2324.org>

Doxyfile
backend/data/data.h
backend/data/glibtree/data_glibtree.c
backend/network/network.h
include/libvscmgmt/types.h
lib/core.c
lib/host.c
lib/image.c
lib/uuid.c
lib/vm.c

index de799e6..ea348c4 100644 (file)
--- a/Doxyfile
+++ b/Doxyfile
@@ -297,17 +297,17 @@ SYMBOL_CACHE_SIZE      = 0
 # Private class members and static file members will be hidden unless
 # the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
 
-EXTRACT_ALL            = YES
+EXTRACT_ALL            = NO
 
 # If the EXTRACT_PRIVATE tag is set to YES all private members of a class
 # will be included in the documentation.
 
-EXTRACT_PRIVATE        = YES
+EXTRACT_PRIVATE        = NO
 
 # If the EXTRACT_STATIC tag is set to YES all static members of a file
 # will be included in the documentation.
 
-EXTRACT_STATIC         = YES
+EXTRACT_STATIC         = NO
 
 # 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  = YES
+EXTRACT_LOCAL_METHODS  = NO
 
 # If this flag is set to YES, the members of anonymous namespaces will be
 # extracted and appear in the documentation as a namespace called
@@ -336,7 +336,7 @@ EXTRACT_ANON_NSPACES   = NO
 # various overviews, but no documentation section is generated.
 # This option has no effect if EXTRACT_ALL is enabled.
 
-HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_MEMBERS     = YES
 
 # If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all
 # undocumented classes that are normally visible in the class hierarchy.
index 02a8c0c..d4963c8 100644 (file)
 #include "../../include/libvscmgmt/types.h"
 #include "../../lib/types.h"
 
+/*!
+ * @brief Initialize the data backend.
+ * @internal
+ *
+ * @note A data backend may read configuration parameters from a file optionally
+ *       given as parameter.
+ */
 void
 _vsc_mgmt_data_init (struct VscError *error,
                      const char *config_filename);
 
+/*!
+ * @brief Cleanup the data backend and forget about all information.
+ * @internal
+ */
 void
 _vsc_mgmt_data_cleanup (void);
 
@@ -46,62 +57,159 @@ _vsc_mgmt_data_cleanup (void);
  * It might be more useful to use some libxml stuff here to push
  * xml data around.
  */
+/*!
+ * @brief Backup all information saved within the data backend to the given FILE pointer.
+ * @internal
+ */
 void
 _vsc_mgmt_data_backup (struct VscError *error, FILE *fp);
 
+
+/*!
+ * @brief Recover all information from the given Xml node.
+ * @internal
+ *
+ * This function will tell the data backend to save all current information and
+ * read the saved state from the given XML document and use this information.
+ */
 void
 _vsc_mgmt_data_recover_start (struct VscError *error, const xmlNode *node);
 
+/*!
+ * @brief Commit the previously started backup.
+ * @internal
+ *
+ * This function will tell the data backend to forget about all information
+ * saved within the backend before starting a backup.
+ */
 void
 _vsc_mgmt_data_recover_commit (void);
 
+/*!
+ * @brief Rollback the backend state to the situation before the recovery.
+ * @internal
+ *
+ * This function will tell the data backend to forget about all information
+ * read by the previously started backup and restore the state present
+ * before the recovery has been started.
+ */
 void
 _vsc_mgmt_data_recover_rollback (void);
 
+/*!
+ * @brief Forget about all VM information but keep host info.
+ * @internal
+ */
 void
 _vsc_mgmt_data_tabula_rasa (struct VscError *error);
 
-/* Host focussed functions */
+
+/*
+ * Host focussed functions
+ */
+
+/*!
+ * @brief Add a host to the data backend.
+ * @internal
+ */
 void
 _vsc_mgmt_data_host_add (struct VscError *error, const struct VscMgmtHost *host);
 
+/*!
+ * @brief Remove a host from the data backend.
+ * @internal
+ *
+ * @note The host struct has to be freed by the caller.
+ */
 void
 _vsc_mgmt_data_host_take (const struct VscMgmtHost *host);
 
+/*!
+ * @brief Lookup a host by it's IP address.
+ * @internal
+*/
 struct VscMgmtHost *
 _vsc_mgmt_data_host_lookup_by_ip (const struct VscMgmtIpv4 *ipv4);
 
+/*!
+ * @brief Get an array containg all hosts known to the data backend.
+ * @internal
+ */
 struct VscMgmtHosts *
 _vsc_mgmt_data_get_all_hosts (void);
 
+/*!
+ * @brief Get the list of VMs deployed on a given host.
+ * @internal
+ */
 struct VscMgmtUuid * /* vm_uuid_list */
 _vsc_mgmt_data_host_get_vm_uuid_list (const struct VscMgmtIpv4 *host_ipv4);
 
+/*!
+ * @brief Return wether there is at least on VM deployed on the given host.
+ * @internal
+ */
 int /* is_empty */
 _vsc_mgmt_data_host_is_empty (const struct VscMgmtIpv4 *host_ipv4);
 
+/*!
+ * @brief Get the libVirt connection pointer of the given host.
+ * @internal
+ */
 virConnectPtr /* libVirt connection */
 _vsc_mgmt_data_host_get_connection (const struct VscMgmtIpv4 *host_ipv4);
 
-/* VM focussed functions */
+
+/*
+ * VM focussed functions
+ */
+
+/*!
+ * @brief Add a VM to the data backend.
+ * @internal
+ */
 void
 _vsc_mgmt_data_vm_add (struct VscError *error, struct VscMgmtVm *vm);
 
+/*!
+ * @brief Remove a VM from the data backend.
+ * @internal
+ *
+ * @note The Vm struct has to be freed by the caller.
+ */
 void
 _vsc_mgmt_data_vm_take (const struct VscMgmtVm *vm);
 
+/*!
+ * @brief Loopup a VM by it's UUID.
+ * @internal
+ */
 struct VscMgmtVm *
 _vsc_mgmt_data_vm_lookup_by_uuid (const struct VscMgmtUuid *vm_uuid);
 
+/*!
+ * @brief Lookup a VM UUID by it's IP address.
+ * @internal
+ */
 void
 _vsc_mgmt_data_vm_get_uuid (const struct VscMgmtIpv4 *vm_ip,
                             struct VscMgmtUuid *uuid_out);
 
+/*!
+ * @brief Get the IP of the host the VM with the given UUID is deployed on.
+ * @internal
+ */
 void
 _vsc_mgmt_data_vm_get_host_ipv4 (struct VscError *error,
                                  const struct VscMgmtUuid *vm_uuid,
                                  struct VscMgmtIpv4 *ip_out);
 
+/*!
+ * @brief Move the given VM to the given host.
+ * @internal
+ *
+ * This function is the backend part of 'migration'.
+ */
 void
 _vsc_mgmt_data_vm_move (struct VscError *error,
                         const struct VscMgmtUuid *vm_uuid,
index fa71774..4832dfa 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
-/*!
- * @file
- */
-
 #include <stdlib.h>
 #include <uuid/uuid.h>
 #include <glib-2.0/glib.h>
@@ -704,7 +700,10 @@ failure:
  *                             private API functions                          *
  ******************************************************************************/
 
-
+/*!
+ * @brief Initialize data backend
+ *
+ */
 void
 _vsc_mgmt_data_init (struct VscError *error, const char *config_filename)
 {
index 170a258..8eea23c 100644 (file)
 #include "../../lib/network.h"
 #include "../../include/libvscmgmt/network.h"
 
+/*!
+ * @internal
+ * @brief Initialize the network backend
+ *
+ * @note A network backend may read configuration parameters from a file optionally
+ *       given as parameter.
+ */
 void
 _vsc_mgmt_network_init (struct VscError *error, const char *config_filename);
 
+/*!
+ * @internal
+ * @brief Cleanup the network backend and forget about all information.
+ */
 void
 _vsc_mgmt_network_cleanup (void);
 
+/*!
+ * @internal
+ * @brief Backup all information saved within the network backend to the given FILE pointer.
+ */
 void
 _vsc_mgmt_network_backup (struct VscError *error, FILE *fp);
 
+/*!
+ * @internal
+ * @brief Recover all information from the given Xml node.
+ *
+ * This function will tell the network backend to save all current information and
+ * read the saved state from the given XML document and use this information.
+ */
 void
 _vsc_mgmt_network_recover_start (struct VscError *error, const xmlNode *node);
 
+/*!
+ * @internal
+ * @brief Commit the previously started backup.
+ *
+ * This function will tell the network backend to forget about all information
+ * saved within the backend before starting a backup.
+ */
 void
 _vsc_mgmt_network_recover_commit (void);
 
+/*!
+ * @internal
+ * @brief Rollback the backend state to the situation before the recovery.
+ *
+ * This function will tell the network backend to forget about all information
+ * read by the previously started backup and restore the state present
+ * before the recovery has been started.
+ */
 void
 _vsc_mgmt_network_recover_rollback (void);
 
+/*!
+ * @internal
+ * @brief Synchronize all information to external resources.
+ *
+ * This function may trigger writing out a generated DHCP config file for example.
+ * It is called at the end of vsc_mgmt_vm_deploy().
+ */
 void
 _vsc_mgmt_network_synchronize (struct VscError *error);
 
+/*!
+ * @brief Forget about all VM information but keep host info.
+ */
 void
 _vsc_mgmt_network_tabula_rasa (struct VscError *error);
 
+/*!
+ * @internal
+ * @brief Acquire an IP address from the given network.
+ *
+ * This function is used to (try to) get an IP from the given network and mark
+ * it as reserved until the decision has been made, if it really is used or
+ * it will be released to the network backend.
+ */
 void
 _vsc_mgmt_network_acquire_ipv4 (struct VscError *error,
                                 const struct VscMgmtUuid *network_uuid,
                                 struct VscMgmtIpv4 *ip_out);
 
+/*!
+ * @internal
+ * @brief Use a previously acquired IP address and get a MAC address for use with the VM.
+ */
 void
 _vsc_mgmt_network_use_ipv4 (struct VscError *error,
                             const struct VscMgmtUuid *network_uuid,
@@ -67,6 +126,10 @@ _vsc_mgmt_network_use_ipv4 (struct VscError *error,
                             struct VscMgmtMac *mac_out,
                             const struct VscMgmtUuid *vm_uuid);
 
+/*!
+ * @internal
+ * @brief Release a previously acquired or used IP address.
+ */
 void
 _vsc_mgmt_network_release_ipv4 (struct VscError *error,
                                 const struct VscMgmtUuid *network_uuid,
index 1663629..edd7c74 100644 (file)
 extern "C" {
 #endif
 
+/*!
+ * @brief The states representing the VM life cycle.
+ */
 enum VscMgmtVmState {
-       VSC_MGMT__VM_STATE__UNDEFINED = 0,
-       VSC_MGMT__VM_STATE__POWERED_OFF,
-       VSC_MGMT__VM_STATE__POWERED_ON,
-       VSC_MGMT__VM_STATE__SUSPENDED,
-       VSC_MGMT__VM_STATE__ERROR,
+       VSC_MGMT__VM_STATE__UNDEFINED = 0,      /**< The state of this domain is undefined */
+       VSC_MGMT__VM_STATE__POWERED_OFF,        /**< The domain is powered of */
+       VSC_MGMT__VM_STATE__POWERED_ON,         /**< The domain is powered on */
+       VSC_MGMT__VM_STATE__SUSPENDED,          /**< The domain is suspended */
+       VSC_MGMT__VM_STATE__ERROR,              /**< The domain is errornous */
 };
 
+/*!
+ * @brief The types of hosts, libvscmgmt currently supports.
+ */
 enum VscMgmtHostType {
-       VSC_MGMT__HOST_TYPE__UNDEFINED = 0,
-       VSC_MGMT__HOST_TYPE__VIRTUAL,
-       VSC_MGMT__HOST_TYPE__XEN,
-       VSC_MGMT__HOST_TYPE__ESX,
-       VSC_MGMT__HOST_TYPE__ESX_VCENTER,
+       VSC_MGMT__HOST_TYPE__UNDEFINED = 0,     /**< The type of this host is undefined */
+       VSC_MGMT__HOST_TYPE__VIRTUAL,           /**< A virtual host within libVirt */
+       VSC_MGMT__HOST_TYPE__XEN,               /**< A host running the Xen hypervisor */
+       VSC_MGMT__HOST_TYPE__ESX,               /**< A host running the ESX hypervisor */
+       VSC_MGMT__HOST_TYPE__ESX_VCENTER,       /**< A host running a VMware VCenter */
 };
 
+/*!
+ * @brief Force level supported by the vsc_mgmt_tabula_rasa() function.
+ */
 enum VscMgmtTabulaRasaForceLevel {
-       VSC_MGMT__TABULA_RASA__KNOWN_ONLY = 0,
-       VSC_MGMT__TABULA_RASA__CHECK_NAME = 1,
-       VSC_MGMT__TABULA_RASA__REALLY_FORCE = 42,
+       VSC_MGMT__TABULA_RASA__KNOWN_ONLY = 0,          /**< Only remove all VMs known to the library */
+       VSC_MGMT__TABULA_RASA__CHECK_NAME = 1,          /**< Only remove VMs whichs name is the same as their UUID */
+       VSC_MGMT__TABULA_RASA__REALLY_FORCE = 42,       /**< Really remove all VMs */
 };
 
+/*!
+ * @brief A VM uuid.
+ */
 struct VscMgmtUuid {
-       struct VscMgmtUuid *next;
-       uuid_t value;
+       struct VscMgmtUuid *next;       /**< The next UUID within the list or NULL */
+       uuid_t value;                   /**< The actual UUID */
 };
 
+/*!
+ * @brief A VM IP address.
+ */
 struct VscMgmtIpv4 {
-       struct VscMgmtIpv4 *next;
-       unsigned char bytes[VSC_MGMT__IPV4__SIZE];
+       struct VscMgmtIpv4 *next;                       /**< The next Ipv4 within the list or NULL */
+       unsigned char bytes[VSC_MGMT__IPV4__SIZE];      /**< The actual IP address in four octets */
 };
 
+/*!
+ * @brief A VM MAC address.
+ */
 struct VscMgmtMac {
-       struct VscMgmtMac *next;
-       unsigned char bytes[VSC_MGMT__MAC__SIZE];
+       struct VscMgmtMac *next;                        /**< The next mac address within the list of NULL */
+       unsigned char bytes[VSC_MGMT__MAC__SIZE];       /**< The actual mac address in six octecs */
 };
 
+/*!
+ * @brief VM resource config parameters.
+ */
 struct VscMgmtVmResourceConfig {
-       struct VscMgmtVmResourceConfig *next;
+       struct VscMgmtVmResourceConfig *next;           /**< The next resource config within the list or NULL */
 
-       int num_cores; /* number of overall CPU cores */
-       int core_clock; /* CPU core clock frequency in MHz */
-       unsigned long memory_size; /* memory size in kilobytes */
+       int num_cores;                                  /**< The number of overall CPU cores */
+       int core_clock;                                 /**< The CPU core clock frequency in MHz */
+       unsigned long memory_size;                      /**< The memory size in kilobytes */
 };
 
+/*!
+ * @brief VM information.
+ */
 struct VscMgmtVmInfo {
-       struct VscMgmtUuid uuid;
-       char *uuid_string;
+       struct VscMgmtUuid uuid;                        /**< The UUID of this VM */
+       char *uuid_string;                              /**< The UUID of this VM as a string */
 
-       char *image_filename;
+       char *image_filename;                           /**< The path to the image file of this VM */
 
-       struct VscMgmtUuid network_uuid;
-       struct VscMgmtIpv4 ipv4;
-       struct VscMgmtMac mac;
+       struct VscMgmtUuid network_uuid;                /**< The network this VM is part of */
+       struct VscMgmtIpv4 ipv4;                        /**< The IP address of this VM */
+       struct VscMgmtMac mac;                          /**< The mac address of this VM */
 
-       enum VscMgmtVmState state;
+       enum VscMgmtVmState state;                      /**< The VM state */
        struct VscMgmtUuid suspension_uuid;
        struct VscMgmtUuid *checkpoint_uuid_list;
-       struct VscMgmtVmResourceConfig resource_config;
+       struct VscMgmtVmResourceConfig resource_config; /**< The VMs resource config */
 
        /* Timing information */
-       struct timeval deployed_at;
-       struct timeval last_state_change;
-       struct timeval last_config_change;
+       struct timeval deployed_at;                     /**< The timestamp this VM has been deployed */
+       struct timeval last_state_change;               /**< The timestamp of the last state change of this VM */
+       struct timeval last_config_change;              /**< The timestamp of the last configuration change of this VM */
 };
 
 struct VscMgmtSuspensionInfo {
@@ -116,17 +140,20 @@ struct VscMgmtCheckpointInfo {
        int dummy;
 };
 
+/*!
+ * @brief Host information.
+ */
 struct VscMgmtHostInfo {
-       struct VscMgmtIpv4 ipv4;
-       enum VscMgmtHostType type;
+       struct VscMgmtIpv4 ipv4;        /**< The IP address of this host */
+       enum VscMgmtHostType type;      /**< The type of this host */
 
-       int num_cores; /* number of overall CPU cores */
-       int core_clock; /* CPU core clock frequency in MHz */
-       unsigned long memory_size; /* memory size in kilobytes */
+       int num_cores;                  /**< The number of overall CPU cores */
+       int core_clock;                 /**< The CPU core clock frequency in MHz */
+       unsigned long memory_size;      /**< The memory size in kilobytes */
 
        /* Timing information */
-       struct timeval last_modification;
-       struct timeval last_resource_allocation;
+       struct timeval last_modification;       /**< The timestamp of the last modification of this host */
+       struct timeval last_resource_allocation; /**< The timestamp the last resource allocation on this host */
 };
 
 #ifdef __cplusplus
index dcf9b10..35fa55f 100644 (file)
@@ -242,9 +242,13 @@ _vsc_mgmt_error_from_libvirt (struct VscError *error, const virConnectPtr connec
  *******************************************************************************/
 
 /*!
- * @brief
+ * @brief Initialize the library and all backends.
  *
  * @note Function is not threadsafe.
+ *
+ * @exception VSC__ERROR_CODE__INVALID_CALL
+ * @exception VSC__ERROR_CODE__TRACE
+ * @exception VSC__ERROR_CODE__LIBVIRT_ERROR
  */
 void
 vsc_mgmt_init (struct VscError *error,
@@ -301,8 +305,10 @@ vsc_mgmt_init (struct VscError *error,
        _vsc_mgmt_initialized = TRUE;
 }
 
+
+
 /*!
- * @brief
+ * @brief Forget about any internal state and free all memory.
  *
  * @note Function is not threadsafe.
  */
@@ -325,7 +331,7 @@ vsc_mgmt_cleanup (void)
 
 
 /*!
- * @brief
+ * @brief Remove all VMs from all known hosts paying respect to the given force level.
  *
  * @note The usual error paradigm use in libvscmgmt does NOT fit for this function.
  *       In contrast to all other functions, vsc_mgmt_tabula_rasa() does NOT abort
@@ -335,6 +341,10 @@ vsc_mgmt_cleanup (void)
  *       So consider the error parameter more like some kind of warning within this
  *       function. If problems occured, the occured flag of the main error will be
  *       set accordingly.
+ *
+ * @exception VSC__ERROR_CODE__INTERNAL_ERROR
+ * @exception VSC__ERROR_CODE__LIBVIRT_ERROR
+ * @exception VSC__ERROR_CODE__GENERIC_BADNESS
  */
 void
 vsc_mgmt_tabula_rasa (struct VscError *error,
@@ -535,7 +545,12 @@ unlock:
 
 
 
-
+/*!
+ * @brief Let the library backups it's internal state to the given file.
+ *
+ * @exception VSC__ERROR_CODE__ERRNO
+ * @exception VSC__ERROR_CODE__TRACE
+ */
 void
 vsc_mgmt_backup (struct VscError *error, const char *filename)
 {
@@ -581,6 +596,15 @@ unlock:
        _vsc_mgmt_unlock();
 }
 
+
+
+/*!
+ * @brief Let the library restore it's internal state from the given backup file.
+ *
+ * @exception VSC__ERROR_CODE__INVALID_ARGUMENT
+ * @exception VSC__ERROR_CODE__INTERNAL_ERROR
+ * @exception VSC__ERROR_CODE__TRACE
+ */
 void
 vsc_mgmt_recover (struct VscError *error, const char *filename)
 {
@@ -686,6 +710,11 @@ rollback:
        goto unlock;
 }
 
+
+
+/*!
+ * @brief Return the library version numbers into the given int pointers.
+ */
 void
 vsc_mgmt_get_version (int *major, int *minor, int *patch)
 {
index ad49fb8..04a4009 100644 (file)
@@ -21,7 +21,6 @@
 /*!
  * @file
  */
-
 #include <string.h>
 
 #include <libvirt/libvirt.h>
@@ -177,7 +176,7 @@ static int _libvirt_cred_types[] = {
 
 static virConnectAuth _libvirt_auth = {
        .credtype = _libvirt_cred_types,
-       .ncredtype = sizeof (_libvirt_cred_types) / sizeof(int),
+       .ncredtype = sizeof (_libvirt_cred_types) / sizeof (int),
        .cb = _libvirt_cred_callback,
        .cbdata = NULL,
 };
@@ -660,7 +659,16 @@ unlock:
  *                             public API functions                           *
  ******************************************************************************/
 
-
+/*!
+ * @brief (Re)read host list from the given filename.
+ *
+ * @note See the file "host_list_file_format.txt" in the docs directory.
+ *
+ * @exception VSC__ERROR_CODE__OUT_OF_MEMORY
+ * @exception VSC__ERROR_CODE__INVALID_ARGUMENT
+ * @exception VSC__ERROR_CODE__LIBVIRT_ERROR
+ * @exception VSC__ERROR_CODE__TRACE
+ */
 void
 vsc_mgmt_read_host_list (struct VscError *error, const char *filename)
 {
@@ -923,6 +931,9 @@ free_parsed_unlock:
  *
  * The list must be freed by the caller via the vsc_mgmt_ipv4_list_free
  * function.
+ *
+ * @exception VSC__ERROR_CODE__OUT_OF_MEMORY
+ * @exception VSC__ERROR_CODE__TRACE
  */
 struct VscMgmtIpv4 * /* host_ipv4_list */
 vsc_mgmt_get_host_ipv4_list (struct VscError *error)
@@ -971,6 +982,11 @@ failure:
 
 
 
+/*!
+ * @brief Get information about the given host represented by it's IP.
+ *
+ * @exception VSC__ERROR_CODE__INVALID_CALL
+ */
 void
 vsc_mgmt_host_get_info (struct VscError *error,
                         const struct VscMgmtIpv4 *host_ipv4,
@@ -1011,6 +1027,9 @@ unlock:
  *
  * The list must be freed by the caller via the vsc_mgmt_uuid_list_free
  * function.
+ *
+ * @exception VSC__ERROR_CODE__INVALID_CALL
+ * @exception VSC__ERROR_CODE__TRACE
  */
 struct VscMgmtUuid * /* vm_uuid_list */
 vsc_mgmt_host_get_vm_uuid_list (struct VscError *error,
index 6a393e7..e7b3518 100644 (file)
@@ -120,9 +120,16 @@ _vsc_mgmt_image_gen_path (const struct VscMgmtUuid *vm_uuid,
 
 
 
-
-
-
+/*!
+ * @brief Deploy the given image for the listed UUIDs.
+ *
+ * @note This function has to be called before calling vsc_mgmt_vm_deploy
+ *       for the listed VMs.
+ *
+ * @exception VSC__ERROR_CODE__TRACE
+ * @exception VSC__ERROR_CODE__INVALID_ARGUMENT
+ * @exception VSC__ERROR_CODE__ERRNO
+ */
 void
 vsc_mgmt_image_deploy (struct VscError *error, const char *src_filename,
                        const struct VscMgmtUuid *vm_uuid_list)
@@ -385,6 +392,18 @@ cleanup:
 }
 
 
+
+/*!
+ * @brief Retract the image(s) of the given VMs.
+ *
+ * @note With the optional image_dest_dirname parameter libvscmgmt can be told
+ *       to move the image file(s) of the given VM(s) into this directory.
+ *       If the parameter is NULL, the image file(s) and the VM image
+ *       directory/ies will be deleted.
+ *
+ * @exception VSC__ERROR_CODE__INVALID_ARGUMENT
+ * @exception VSC__ERROR_CODE__ERRNO
+ */
 void
 vsc_mgmt_image_retract (struct VscError *error,
                         const struct VscMgmtUuid *vm_uuid,
index b7624d4..90dccc5 100644 (file)
@@ -34,6 +34,8 @@
 
 /*!
  * @brief Parses a UUID from string representation.
+ *
+ * @exception VSC__ERROR_CODE__INVALID_ARGUMENT
  */
 void
 vsc_mgmt_uuid_parse (struct VscError *error, const char *uuid_string,
@@ -79,6 +81,7 @@ vsc_mgmt_uuid_list_append (struct VscMgmtUuid **uuid_list,
 /*!
  * @brief VscMgmtUuid specific version of vsc_list_append_clone().
  * @internal
+
  */
 void
 _vsc_mgmt_uuid_list_append_clone (struct VscError *error,
@@ -162,6 +165,8 @@ _vsc_mgmt_uuid_clone (struct VscError *error,
        return uuid_clone;
 }
 
+
+
 void
 _vsc_mgmt_uuid_free (struct VscMgmtUuid **uuid)
 {
@@ -170,6 +175,12 @@ _vsc_mgmt_uuid_free (struct VscMgmtUuid **uuid)
        vsc_free (uuid);
 }
 
+
+/*!
+ * @brief Generate a list of UUIDs containing num_uuids elements.
+ *
+ * @exception VSC__ERROR_CODE__TRACE
+ */
 struct VscMgmtUuid *
 vsc_mgmt_uuid_generate (struct VscError *error, unsigned int num_uuids)
 {
index f296a2b..e5f9ffa 100644 (file)
--- a/lib/vm.c
+++ b/lib/vm.c
@@ -537,7 +537,24 @@ _vm_get_domain_pointer (struct VscError *error, const struct VscMgmtVm *vm)
  *******************************************************************************/
 
 
-
+/*!
+ * @brief Deploy a set of virtual machines on a set of cluster hosts.
+ *
+ * This functions deployes a set of virtual machines identified by their UUIDs
+ * with a corresponding list of resource configurations on a set of hosts
+ * identified by their IPs and uses IPs from the network identified by it's
+ * UUID for use by the VMs.
+ *
+ * The mapping between the (host, VM UUID and resource config) is done by the
+ * position of the corresponding entry within the lists. All lists have to be
+ * of the same size.
+ *
+ * @exception VSC__ERROR_CODE__INVALID_ARGUMENT
+ * @exception VSC__ERROR_CODE__INVALID_CALL
+ * @exception VSC__ERROR_CODE__ERRNO
+ * @exception VSC__ERROR_CODE__LIBVIRT_ERROR
+ * @exception VSC__ERROR_CODE__TRACE
+ */
 void
 vsc_mgmt_vm_deploy (struct VscError *error,
                     const struct VscMgmtIpv4 *host_ipv4_list,
@@ -850,6 +867,13 @@ rollback_cleanup_unlock:
 
 
 
+/*!
+ * @brief Retract the given VM from the cluster.
+ *
+ * @exception VSC__ERROR_CODE__INVALID_ARGUMENT
+ * @exception VSC__ERROR_CODE__ERRNO
+ * @exception VSC__ERROR_CODE__TRACE
+ */
 void
 vsc_mgmt_vm_retract (struct VscError *error,
                      const struct VscMgmtUuid *vm_uuid)
@@ -949,7 +973,17 @@ unlock:
 }
 
 
-
+/*!
+ * @brief Power on the given VM and implictly set the CPU resource parameters.
+ *
+ * @warning This function can cause an causes_inconsistency error.
+ *
+ * @exception VSC__ERROR_CODE__INVALID_ARGUMENT
+ * @exception VSC__ERROR_CODE__ERRNO
+ * @exception VSC__ERROR_CODE__INTERNAL_ERROR
+ * @exception VSC__ERROR_CODE__LIBVIRT_ERROR
+ * @exception VSC__ERROR_CODE__TRACE
+ */
 void
 vsc_mgmt_vm_power_on (struct VscError *error,
                       const struct VscMgmtUuid *vm_uuid)
@@ -1053,6 +1087,15 @@ unlock:
 
 
 
+/*!
+ * @brief Power of the given VM.
+ *
+ * @exception VSC__ERROR_CODE__INVALID_ARGUMENT
+ * @exception VSC__ERROR_CODE__ERRNO
+ * @exception VSC__ERROR_CODE__INTERNAL_ERROR
+ * @exception VSC__ERROR_CODE__LIBVIRT_ERROR
+ * @exception VSC__ERROR_CODE__TRACE
+ */
 void
 vsc_mgmt_vm_power_off (struct VscError *error,
                        const struct VscMgmtUuid *vm_uuid)
@@ -1133,6 +1176,18 @@ unlock:
 
 
 
+/*!
+ * @brief Power off the given VM.
+ *
+ * This function will just power off the given VM, it will not try to shutdown
+ * the operating system running within the virtual machine beforehand.
+ *
+ * @exception VSC__ERROR_CODE__INVALID_ARGUMENT
+ * @exception VSC__ERROR_CODE__ERRNO
+ * @exception VSC__ERROR_CODE__INTERNAL_ERROR
+ * @exception VSC__ERROR_CODE__LIBVIRT_ERROR
+ * @exception VSC__ERROR_CODE__TRACE
+ */
 void
 vsc_mgmt_vm_reboot (struct VscError *error,
                     const struct VscMgmtUuid *vm_uuid)
@@ -1210,6 +1265,15 @@ unlock:
 
 
 
+/*!
+ * @brief Migrate the given VM to the given host.
+ *
+ * @exception VSC__ERROR_CODE__INVALID_ARGUMENT
+ * @exception VSC__ERROR_CODE__ERRNO
+ * @exception VSC__ERROR_CODE__INTERNAL_ERROR
+ * @exception VSC__ERROR_CODE__LIBVIRT_ERROR
+ * @exception VSC__ERROR_CODE__TRACE
+ */
 void
 vsc_mgmt_vm_migrate (struct VscError *error,
                      const struct VscMgmtUuid *vm_uuid,
@@ -1338,6 +1402,9 @@ unlock:
 
 
 
+/*!
+ * @brief Get the UUID of the given VM identified by it's IP.
+ */
 void
 vsc_mgmt_vm_get_uuid (struct VscError *error,
                       const struct VscMgmtIpv4 *vm_ipv4,
@@ -1357,6 +1424,11 @@ vsc_mgmt_vm_get_uuid (struct VscError *error,
 
 
 
+/*!
+ * @brief Get the IP of the host the given VM is currently running on.
+ *
+ * @exception VSC__ERROR_CODE__TRACE
+ */
 void
 vsc_mgmt_vm_get_host (struct VscError *error,
                       const struct VscMgmtUuid *vm_uuid,
@@ -1383,6 +1455,14 @@ unlock:
 
 
 
+/*!
+ * @brief Retrieve information about the given VM.
+ *
+ * @note The given VmInfo struct has to be freed by the user.
+ * @note There exists a vsc_mgmt_vm_info_cleanup function to clean the VmInfo struct.
+ *
+ * @exception VSC__ERROR_CODE__INVALID_ARGUMENT
+ */
 void
 vsc_mgmt_vm_get_info (struct VscError *error,
                       const struct VscMgmtUuid *vm_uuid,
@@ -1420,6 +1500,9 @@ unlock:
 
 
 
+/*!
+ * @brief Cleanup the information within the given VmInfo struct.
+ */
 void
 vsc_mgmt_vm_info_cleanup (struct VscMgmtVmInfo *vm_info)
 {
@@ -1439,7 +1522,15 @@ vsc_mgmt_vm_info_cleanup (struct VscMgmtVmInfo *vm_info)
 
 
 
-
+/*!
+ * @brief Update the resource config values of the given VM.
+ *
+ * @exception VSC__ERROR_CODE__INVALID_ARGUMENT
+ * @exception VSC__ERROR_CODE__INTERNAL_ERROR
+ * @exception VSC__ERROR_CODE__ERRNO
+ * @exception VSC__ERROR_CODE__LIBVIRT_ERROR
+ * @exception VSC__ERROR_CODE__TRACE
+ */
 void
 vsc_mgmt_vm_set_resource_config (struct VscError *error,
                                  const struct VscMgmtUuid *vm_uuid,