- code documentation cleaned
authorJan Hutter <jhutter@hsr.ch>
Fri, 25 Nov 2005 08:36:26 +0000 (08:36 -0000)
committerJan Hutter <jhutter@hsr.ch>
Fri, 25 Nov 2005 08:36:26 +0000 (08:36 -0000)
Source/charon/utils/iterator.h
Source/charon/utils/logger_manager.c
Source/charon/utils/logger_manager.h

index 17deb63..8a2a3c3 100644 (file)
@@ -31,11 +31,12 @@ typedef struct iterator_t iterator_t;
  * iterator_t defines an interface for iterating over collections.
  * It allows searching, deleting, updating and inserting.
  * 
+ * @ingroup utils 
  */
 struct iterator_t {
 
        /**
-        * @brief Moves to the next element, if available.
+        * Moves to the next element, if available.
         * 
         * @param this                  calling object
         * @return
@@ -45,39 +46,39 @@ struct iterator_t {
        bool (*has_next) (iterator_t *this);
 
        /**
-        * @brief Returns the current value at the iterator position.
+        * Returns the current value at the iterator position.
         * 
         * @param this                  calling object
         * @param [out]value    value is set to the current value at iterator position
         * @return
-        *                                              - SUCCESS, or
-        *                                              - FAILED if iterator is on an invalid state
+        *                                              - SUCCESS
+        *                                              - FAILED if list is empty
         */
        status_t (*current) (iterator_t *this, void **value);
        
        /**
-        * @brief Inserts a new item before the given iterator position.
+        * Inserts a new item before the given iterator position.
         * 
         * The iterator position is not changed after inserting
         * 
         * @param this                  calling iterator
         * @param [in]item              value to insert in list
         * @return 
-        *                                              - SUCCESS if succeeded, 
-        *                                              - FAILED otherwise
+        *                                              - SUCCESS
+        *                                              - FAILED
         */
        status_t (*insert_before) (iterator_t *this, void *item);
 
        /**
-        * @brief Inserts a new item after the given iterator position.
+        * Inserts a new item after the given iterator position.
         * 
         * The iterator position is not changed after inserting.
         * 
         * @param this                  calling iterator
         * @param [in]item              value to insert in list
         * @return
-        *                                              - SUCCESS if succeeded, 
-        *                                              - FAILED otherwise
+        *                                              - SUCCESS 
+        *                                              - FAILED
         */
        status_t (*insert_after) (iterator_t *this, void *item);
 
@@ -91,8 +92,8 @@ struct iterator_t {
         * 
         * @param linked_list   calling object
         * @return 
-        *                                              - SUCCESS if succeeded, 
-        *                                              - FAILED otherwise
+        *                                              - SUCCESS
+        *                                              - FAILED
         */
        status_t (*remove) (iterator_t *iterator);
                          
@@ -104,9 +105,7 @@ struct iterator_t {
         * with the resetted iterator.
         * 
         * @param this                  calling object
-        * @return 
-        *                                              - SUCCESS if succeeded, 
-        *                                              - FAILED otherwise
+        * @return                              SUCCESS in any case
         */
        status_t (*reset) (iterator_t *this);
 
@@ -114,9 +113,8 @@ struct iterator_t {
         * @brief Destroys an iterator.
         * 
         * @param this                  iterator to destroy
-        * @return 
-        *                                              - SUCCESS if succeeded, 
-        *                                              - FAILED otherwise
+        * @return                              SUCCESS in any case
+        * 
         */
        status_t (*destroy) (iterator_t *this);
 };
index 5f97bce..61c733d 100644 (file)
@@ -1,7 +1,7 @@
 /**
  * @file logger_manager.c
  *
- * @brief Logger manager. Manages globaly all logger objects
+ * @brief Implementation of logger_manager_t.
  *
  */
 
@@ -49,8 +49,12 @@ mapping_t logger_context_t_mappings[] = {
  */
 #define MAX_LOGGER_NAME 45
 
+
 typedef struct private_logger_manager_t private_logger_manager_t;
 
+/** 
+ * Private data of logger_manager_t object.
+ */
 struct private_logger_manager_t {      
        /**
         * Public data.
@@ -73,45 +77,52 @@ struct private_logger_manager_t {
        pthread_mutex_t mutex;
        
        /**
-        * Default logger level for a created logger used if no specific logger_level is set
+        * Default logger level for a created logger used 
+        * if no specific logger_level is set.
         */
        logger_level_t default_log_level;
        
        /**
         * Sets set logger_level of a specific context.
+        * 
         * @param this                  calling object
         * @param context               context to set level
         * @param logger_level  logger_level to set
         * @param enable                enable specific level or disable it
-        * @return SUCCESS
+        * @return                              
+        *                                              - SUCCESS
+        *                                              - OUT_OF_RES
         */
        status_t (*set_logger_level) (private_logger_manager_t *this, logger_context_t context,logger_level_t logger_level,bool enable);
        
 };
 
-/**
- * Entry in the logger_levels linked list
- */
+
 typedef struct logger_levels_entry_t logger_levels_entry_t;
 
+/**
+ * Entry in the logger_levels linked list.
+ * 
+ * This entry specifies the current log level for 
+ * logger_t objects in specific context.
+ */
 struct logger_levels_entry_t {
        logger_context_t context;
        logger_level_t level;
 };
 
-/**
- * Entry in the loggers linked list
- */
 typedef struct loggers_entry_t loggers_entry_t;
 
+/**
+ * Entry in the loggers linked list.
+ */
 struct loggers_entry_t {
        logger_context_t context;
        logger_t *logger;
 };
 
 /**
- * Implements logger_manager_t-function create_logger.
- * @see logger_manager_s.create_logger.
+ * Implementation of logger_manager_t.create_logger.
  */
 static logger_t *create_logger(private_logger_manager_t *this, logger_context_t context, char * name)
 {
@@ -189,8 +200,7 @@ static logger_t *create_logger(private_logger_manager_t *this, logger_context_t
 }
 
 /**
- * Implements logger_manager_t-function get_logger_level.
- * @see logger_manager_s.get_logger_level.
+ * Implementation of logger_manager_t.get_logger_level.
  */
 static logger_level_t get_logger_level (private_logger_manager_t *this, logger_context_t context)
 {
@@ -229,8 +239,7 @@ static logger_level_t get_logger_level (private_logger_manager_t *this, logger_c
 }
 
 /**
- * Implements logger_manager_t-function destroy_logger.
- * @see logger_manager_s.destroy_logger.
+ * Implementation of logger_manager_t.destroy_logger.
  */
 static status_t destroy_logger (private_logger_manager_t *this,logger_t *logger)
 {
@@ -270,8 +279,7 @@ static status_t destroy_logger (private_logger_manager_t *this,logger_t *logger)
 }
 
 /**
- * Implements private_logger_manager_t-function set_logger_level.
- * @see private_logger_manager_s.set_logger_level.
+ * Implementation of private_logger_manager_t.set_logger_level.
  */
 static status_t set_logger_level (private_logger_manager_t *this, logger_context_t context,logger_level_t logger_level,bool enable)
 {
@@ -373,8 +381,7 @@ static status_t set_logger_level (private_logger_manager_t *this, logger_context
 }
 
 /**
- * Implements logger_manager_t-function enable_logger_level.
- * @see logger_manager_s.enable_logger_level.
+ * Implementation of logger_manager_t.enable_logger_level.
  */
 static status_t enable_logger_level (private_logger_manager_t *this, logger_context_t context,logger_level_t logger_level)
 {
@@ -382,8 +389,7 @@ static status_t enable_logger_level (private_logger_manager_t *this, logger_cont
 }
 
 /**
- * Implements logger_manager_t-function disable_logger_level.
- * @see logger_manager_s.disable_logger_level.
+ * Implementation of logger_manager_t.disable_logger_level.
  */
 static status_t disable_logger_level (private_logger_manager_t *this, logger_context_t context,logger_level_t logger_level)
 {
@@ -391,8 +397,7 @@ static status_t disable_logger_level (private_logger_manager_t *this, logger_con
 }
 
 /**
- * Implements logger_manager_t-function destroy.
- * @see logger_manager_s.destroy.
+ * Implementation of logger_manager_t.destroy.
  */
 static status_t destroy(private_logger_manager_t *this)
 {
@@ -429,7 +434,7 @@ static status_t destroy(private_logger_manager_t *this)
 }
 
 /*
- * Described in header
+ * Described in header.
  */
 logger_manager_t *logger_manager_create(logger_level_t default_log_level)
 {
index de37e1e..afc199c 100644 (file)
@@ -1,7 +1,7 @@
 /**
  * @file logger_manager.h
  *
- * @brief Logger manager. Manages globaly all logger objects
+ * @brief Interface of logger_manager_t.
  *
  */
 
@@ -31,6 +31,8 @@ typedef enum logger_context_t logger_context_t;
 
 /**
  * @brief Context of a specific logger 
+ * 
+ * @ingroup utils
  */
 enum logger_context_t {
        PARSER,
@@ -52,76 +54,86 @@ enum logger_context_t {
 typedef struct logger_manager_t logger_manager_t;
 
 /**
- * @brief The logger_manager_t object
+ * Class to manage logger_t objects.
+ * 
+ * @ingroup utils
  */
 struct logger_manager_t {
        
        /**
         * @brief Gets a logger_t object for a specific logger context.
         * 
-        * @warning logger_t objects which are not destroyed over function
-        * #logger_manager_s.destroy_logger are destroyed in logger_managers 
+        * @warning Objects of type logger_t which are not destroyed over function
+        * #logger_manager_t.destroy_logger are destroyed in logger_managers 
         * destroy function. Don't use logger_t's own destroy function with 
         * managed logger_t objects.
         *
         * @param this                  logger_manager_t object
-        * @param context               logger_context to use the logger for.
+        * @param context               logger_context to use the logger for
         * @param[out] logger   pointer to a a place where the new logger is stored
         * @param name                  name for the new logger. Context name is already included 
-        *                                              and has not to be specified (so NULL is allowed).
-        * @return
-        *                                              - logger_t on SUCCESS
-        *                                              - NULL otherwise
+        *                                              and has not to be specified (so NULL is allowed)
+        * @return                              
+        *                                              - logger_t object
+        *                                              - NULL if out of ressources
         */
        logger_t *(*create_logger) (logger_manager_t *this, logger_context_t context, char *name);
        
        
        /**
-        * @brief Destroys a logger_t object which is not used anymore
+        * @brief Destroys a logger_t object which is not used anymore.
         * 
-        * @warning logger_t objects which are not destroyed over function
-        * #logger_manager_s.destroy_logger are destroyed in logger_managers 
+        * @warning Objects of type logger_t which are not destroyed over function
+        * #logger_manager_t.destroy_logger are destroyed in logger_managers 
         * destroy function.
         *
         * @param this          logger_manager_t object
         * @param logger                pointer to the logger which has to be destroyed
-        * @return
-        *                                      - SUCCESS
-        *                                      - OUT_OF_RES
+        * @return                      - SUCCESS
+        *                                      - OUT_OF_RES (when searching the specific logger_t object)
         *                                      - NOT_FOUND
         */
        status_t (*destroy_logger) (logger_manager_t *this,logger_t *logger);
        
        /**
         * Returns the set logger_level of a specific context or 0.
+        * 
         * @param this                  calling object
         * @param context               context to check level
-        * @return logger_level         for the given logger_context
+        * @return                              logger_level for the given logger_context
         */
        logger_level_t (*get_logger_level) (logger_manager_t *this, logger_context_t context);
        
        /**
         * Enables a logger_level of a specific context.
+        * 
         * @param this                  calling object
         * @param context               context to set level
         * @param logger_level  logger_level to eanble
-        * @return SUCCESS
+        * @return                              
+        *                                              - SUCCESS
+        *                                              - OUT_OF_RES
         */
        status_t (*enable_logger_level) (logger_manager_t *this, logger_context_t context,logger_level_t logger_level);
                
 
        /**
         * Disables a logger_level of a specific context.
+        * 
         * @param this                  calling object
         * @param context               context to set level
         * @param logger_level  logger_level to disable
-        * @return SUCCESS
+        * @return
+        *                                              - SUCCESS
+        *                                              - OUT_OF_RES
         */
        status_t (*disable_logger_level) (logger_manager_t *this, logger_context_t context,logger_level_t logger_level);
 
 
        /**
-        * @brief destroys a logger_manager_t object.
+        * @brief Destroys a logger_manager_t object.
+        * 
+        * All remaining managed logger_t objects are also destroyed.
         *
         * @param this          logger_manager_t object
         * @return
@@ -134,8 +146,11 @@ struct logger_manager_t {
  * @brief Constructor to create a logger_manager_t object.
  *
  * @param default_log_level    default log level for a context
- * @return                                     logger_manager_t object or NULL if failed
+ * @return                                     
+ *                                                     - logger_manager_t object
+ *                                                     - NULL if out of ressources
  * 
+ * @ingroup utils
  */
 logger_manager_t *logger_manager_create(logger_level_t default_log_level);