Some minor comment fixes.

src/libstrongswan/utils/linked_list.h

@@ -107,12 +107,14 @@ struct linked_list_t {
 	void (*remove_at)(linked_list_t *this, enumerator_t *enumerator);
 
 	/**
-	 * Remove items from the list matching item.
+	 * Remove items from the list matching the given item.
 	 *
-	 * If a compare function is given, it is called for each item, where
+	 * If a compare function is given, it is called for each item, with the
-	 * the first parameter is the current list item and the second parameter
+	 * first parameter being the current list item and the second parameter
-	 * is the supplied item parameter.
+	 * being the supplied item. Return TRUE from the compare function to remove
-	 * If compare is NULL, compare is done by pointer.
+	 * the item, return FALSE to keep it in the list.
+	 *
+	 * If compare is NULL, comparison is done by pointers.
 	 *
 	 * @param item		item to remove/pass to comparator
 	 * @param compare	compare function, or NULL
@@ -203,6 +205,8 @@ struct linked_list_t {
 	 * which can be evalutated at compile time using the offsetof
 	 * macro, e.g.: list->invoke(list, offsetof(object_t, method));
 	 *
+	 * @warning Only use pointers as user supplied data.
+	 *
 	 * @param offset	offset of the method to invoke on objects
 	 * @param ...		user data to supply to called function (limited to 5 arguments)
 	 */
@@ -211,6 +215,8 @@ struct linked_list_t {
 	/**
 	 * Invoke a function on all of the contained objects.
 	 *
+	 * @warning Only use pointers as user supplied data.
+	 *
 	 * @param function	offset of the method to invoke on objects
 	 * @param ...		user data to supply to called function (limited to 5 arguments)
 	 */