From f673471b10622a5b9f0d9d0fa66cfc951541b91d Mon Sep 17 00:00:00 2001 From: Martin Willi Date: Mon, 5 Dec 2005 16:30:53 +0000 Subject: [PATCH] - some doc updates --- Source/charon/utils/identification.c | 6 +++-- Source/charon/utils/identification.h | 36 ++++++++++++++++++---------- Source/charon/utils/iterator.h | 17 +++++++++---- Source/charon/utils/linked_list.h | 13 ++++++---- Source/charon/utils/logger_manager.h | 13 ++++++++-- 5 files changed, 60 insertions(+), 25 deletions(-) diff --git a/Source/charon/utils/identification.c b/Source/charon/utils/identification.c index 2e594dd7f..b2dc299f4 100644 --- a/Source/charon/utils/identification.c +++ b/Source/charon/utils/identification.c @@ -125,7 +125,7 @@ static void destroy(private_identification_t *this) allocator_free(this); } -/** +/* * Generic constructor used for the other twos */ static private_identification_t *identification_create() @@ -240,7 +240,9 @@ identification_t *identification_create_from_encoding(id_type_t type, chunk_t en } } - /* build string, must be cloned */ + /* build string, must be cloned since + * inet_ntoa points to a subsequently + * overwritten buffer */ this->string = allocator_alloc(strlen(string)+1); strcpy(this->string, string); diff --git a/Source/charon/utils/identification.h b/Source/charon/utils/identification.h index bc2889760..02a5a2e60 100644 --- a/Source/charon/utils/identification.h +++ b/Source/charon/utils/identification.h @@ -30,11 +30,14 @@ typedef enum id_type_t id_type_t; /** - * ID Types of a ID payload. + * @brief ID Types of a ID payload. + * + * @see identification_t * * @ingroup utils */ enum id_type_t { + /** * ID data is a single four (4) octet IPv4 address. */ @@ -79,6 +82,9 @@ enum id_type_t { ID_KEY_ID = 11 }; +/** + * string amppings for id_type_t + */ extern mapping_t id_type_m[]; typedef struct identification_t identification_t; @@ -87,14 +93,20 @@ typedef struct identification_t identification_t; * @brief Generic identification, such as used in ID payload. * * The following types are possible: - * * - ID_IPV4_ADDR - * - ID_FQDN (not implemented) - * - ID_RFC822_ADDR (not implemented) - * - ID_IPV6_ADDR (not implemented) - * - ID_DER_ASN1_DN (not implemented) - * - ID_DER_ASN1_GN (not implemented) - * - ID_KEY_ID (not implemented) + * - ID_FQDN* + * - ID_RFC822_ADDR* + * - ID_IPV6_ADDR* + * - ID_DER_ASN1_DN* + * - ID_DER_ASN1_GN* + * - ID_KEY_ID* + * (* = string conversion not supported) + * + * @b Constructors: + * - identification_create_from_string() + * - identification_create_from_encoding() + * + * @todo Implement other types. * * @ingroup utils */ @@ -134,7 +146,7 @@ struct identification_t { * * @param this the identification_t_object * @param other other identification_t_object - * @return string + * @return TRUE if the IDs are equal */ bool (*equals) (identification_t *this,identification_t *other); @@ -142,7 +154,7 @@ struct identification_t { /** * @brief Destroys a identification_t object. * - * @param this identification_t object + * @param this identification_t object */ void (*destroy) (identification_t *this); }; @@ -150,7 +162,7 @@ struct identification_t { /** * @brief Creates an identification_t object from a string. * - * @param type type of this id, such as ID_IPV4_ADDR or ID_RFC822_ADDR + * @param type type of this id, such as ID_IPV4_ADDR * @param string input string, which will be converted * @return * - created identification_t object, or @@ -164,7 +176,7 @@ identification_t * identification_create_from_string(id_type_t type, char *strin /** * @brief Creates an identification_t object from an encoded chunk. * - * @param type type of this id, such as ID_IPV4_ADDR or ID_RFC822_ADDR + * @param type type of this id, such as ID_IPV4_ADDR * @param encoded encoded bytes, such as from identification_t.get_encoding * @return created identification_t object * diff --git a/Source/charon/utils/iterator.h b/Source/charon/utils/iterator.h index f0e66a093..55d1c5de8 100644 --- a/Source/charon/utils/iterator.h +++ b/Source/charon/utils/iterator.h @@ -31,12 +31,21 @@ typedef struct iterator_t iterator_t; * iterator_t defines an interface for iterating over collections. * It allows searching, deleting, updating and inserting. * + * @b Constructors: + * - via linked_list_t.create_iterator, or + * - any other class which supports this interface + * + * @see linked_list_t + * * @ingroup utils */ struct iterator_t { /** - * Moves to the next element, if available. + * @brief Moves to the next element, if available. + * + * A newly created iterator doesn't point to any item, + * call has_next first to point it to the first item. * * @param this calling object * @return @@ -46,7 +55,7 @@ struct iterator_t { bool (*has_next) (iterator_t *this); /** - * Returns the current value at the iterator position. + * @brief 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 @@ -57,7 +66,7 @@ struct iterator_t { status_t (*current) (iterator_t *this, void **value); /** - * Inserts a new item before the given iterator position. + * @biref Inserts a new item before the given iterator position. * * The iterator position is not changed after inserting * @@ -92,7 +101,7 @@ struct iterator_t { status_t (*replace) (iterator_t *this, void **old_item, void *new_item); /** - * @brief removes an element from list at the given iterator position. + * @brief Removes an element from list at the given iterator position. * * The position of the iterator is set in the following order: * - to the item before, if available diff --git a/Source/charon/utils/linked_list.h b/Source/charon/utils/linked_list.h index 779252e0f..e01b7c1a3 100644 --- a/Source/charon/utils/linked_list.h +++ b/Source/charon/utils/linked_list.h @@ -34,6 +34,9 @@ typedef struct linked_list_t linked_list_t; * * @warning Access to an object of this type is not thread-save. * + * @b Costructors: + * - linked_list_create() + * * @see job_queue_t, event_queue_t, send_queue_t * * @ingroup utils @@ -43,8 +46,8 @@ struct linked_list_t { /** * @brief Gets the count of items in the list. * - * @param linked_list calling object - * @return number of items in list + * @param linked_list calling object + * @return number of items in list */ int (*get_count) (linked_list_t *linked_list); @@ -53,9 +56,9 @@ struct linked_list_t { * * @warning Created iterator_t object has to get destroyed by the caller. * - * @param linked_list calling object - * @param[in] forward iterator direction (TRUE: front to end) - * @return new iterator_t object + * @param linked_list calling object + * @param[in] forward iterator direction (TRUE: front to end) + * @return new iterator_t object */ iterator_t * (*create_iterator) (linked_list_t *linked_list, bool forward); diff --git a/Source/charon/utils/logger_manager.h b/Source/charon/utils/logger_manager.h index 7658e4282..63b043fc6 100644 --- a/Source/charon/utils/logger_manager.h +++ b/Source/charon/utils/logger_manager.h @@ -30,7 +30,7 @@ typedef enum logger_context_t logger_context_t; /** - * @brief Context of a specific logger + * @brief Context of a specific logger. * * @ingroup utils */ @@ -56,7 +56,16 @@ enum logger_context_t { typedef struct logger_manager_t logger_manager_t; /** - * Class to manage logger_t objects. + * @brief Class to manage logger_t objects. + * + * The logger manager stores all loggers in a list and + * allows their manipulation. Via a logger_context_t, the loglevel + * of a specific logging type can be adjusted at runtime. + * + * @b Constructors: + * - logger_manager_create() + * + * @see logger_t * * @ingroup utils */