- some doc updates

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);
 	

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_FQDN*
- * - ID_RFC822_ADDR  (not implemented)
+ * - ID_RFC822_ADDR*
- * - ID_IPV6_ADDR (not implemented)
+ * - ID_IPV6_ADDR*
- * - ID_DER_ASN1_DN  (not implemented)
+ * - ID_DER_ASN1_DN*
- * - ID_DER_ASN1_GN (not implemented)
+ * - ID_DER_ASN1_GN*
- * - ID_KEY_ID (not implemented)
+ * - 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
  * 

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

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
+	 * @param linked_list 	calling object
-	 * @return 					number of items in list
+	 * @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 linked_list 	calling object
-	 * @param[in] forward 		iterator direction (TRUE: front to end)
+	 * @param[in] forward 	iterator direction (TRUE: front to end)
-	 * @return					new iterator_t object
+	 * @return				new iterator_t object
 	 */
 	iterator_t * (*create_iterator) (linked_list_t *linked_list, bool forward);
 

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
  */