Refactoring:core:Add some more documentation

Signed-off-by: mvglasow <michael -at- vonglasow.com>

git-svn-id: http://svn.code.sf.net/p/navit/code/trunk/navit@5948 ffa7fe5e-494d-0410-b361-a75ebd5db220

8 files changed, 470 insertions, 73 deletions

diff --git a/navit/attr.c b/navit/attr.c
index 1c13c3fbf..defc92ce1 100644
--- a/navit/attr.c
+++ b/navit/attr.c
@@ -1,4 +1,4 @@
-/**
+/*
  * Navit, a modular navigation system.
  * Copyright (C) 2005-2008 Navit Team
  *
@@ -16,6 +16,15 @@
  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  * Boston, MA  02110-1301, USA.
  */
+ 
+/** @file attr.c
+ * @brief Attribute handling code
+ * 
+ * Structures and functions for working with attributes.
+ *
+ * @author Navit Team
+ * @date 2005-2014
+ */
 
 #include <stdlib.h>
 #include <string.h>
@@ -74,6 +83,14 @@ attr_destroy_hash(void)
 	attr_hash=NULL;
 }
 
+/** 
+ * @brief Converts a string to an attr_type
+ *
+ * This function reads a string and returns the corresponding attr_type.
+ *
+ * @param name The attribute name
+ * @return The corresponding {@code attr_type}, or {@code attr_none} if the string specifies a nonexistent or invalid attribute type.
+ */
 enum attr_type
 attr_from_name(const char *name)
 {
@@ -93,6 +110,14 @@ static int attr_match(enum attr_type search, enum attr_type found);
 
 
 
+/** 
+ * @brief Converts an attr_type to a string
+ *
+ * @param attr The attribute type to be converted.
+ * @return The attribute name, or NULL if an invalid value was passed as {@code attr}.
+ * The calling function should create a copy of the string if it needs to alter it or relies on the
+ * string being available permanently.
+ */
 char *
 attr_to_name(enum attr_type attr)
 {
@@ -105,6 +130,16 @@ attr_to_name(enum attr_type attr)
 	return NULL; 
 }
 
+/** 
+ * @brief Creates an attribute from text information
+ *
+ * This function creates an attribute from two strings specifying the name and
+ * the value.
+ *
+ * @param name The name of the new attribute
+ * @param value The value of the new attribute
+ * @return The new attribute
+ */
 struct attr *
 attr_new_from_text(const char *name, const char *value)
 {
@@ -250,6 +285,12 @@ attr_new_from_text(const char *name, const char *value)
 	return ret;
 }
 
+/** 
+ * @brief Converts access flags to a human-readable string.
+ *
+ * @param flags The flags as a number
+ * @return The flags in human-readable form
+ */
 static char *
 flags_to_text(int flags)
 {
@@ -289,6 +330,19 @@ flags_to_text(int flags)
 	return ret;
 }
 
+/** 
+ * @brief Converts attribute data to human-readable text
+ *
+ * @param attr The attribute to be formatted
+ * @param sep The separator to insert between a numeric value and its unit. If NULL, nothing will be inserted.
+ * @param fmt Set to {@code attr_format_with_units} if {@code attr} is of type {@code attr_destination_length}
+ * or {@code attr_destination_time} or a group type which might contain attributes of those types. Ignored for
+ * all other attribute types.
+ * @param def_fmt Not used
+ * @param map The translation map. This is only needed for string type attributes or group type
+ * attributes which might contain strings. It can be NULL for other attribute types. If a string
+ * type attribute is encountered and {@code map} is NULL, the string will be returned unchanged.
+ */
 char *
 attr_to_text_ext(struct attr *attr, char *sep, enum attr_format fmt, enum attr_format def_fmt, struct map *map)
 {
@@ -407,7 +461,7 @@ attr_to_text_ext(struct attr *attr, char *sep, enum attr_format fmt, enum attr_f
  * This function is just a wrapper around {@code attr_to_text_ext()}.
  *
  * @param attr The attribute to convert
- * @param map
+ * @param map The translation map, see {@code attr_to_text_ext()}
  * @param pretty Not used
  */
 char *
@@ -416,6 +470,18 @@ attr_to_text(struct attr *attr, struct map *map, int pretty)
 	return attr_to_text_ext(attr, NULL, attr_format_default, attr_format_default, map);
 }
 
+/** 
+ * @brief Searches for an attribute of a given type
+ *
+ * This function searches an array of pointers to attributes for a given
+ * attribute type and returns the first match.
+ *
+ * @param attrs Points to the array of attribute pointers to be searched
+ * @param last Not used
+ * @param attr_type The attribute type to search for. Generic types (such as
+ * attr_any or attr_any_xml) are NOT supported.
+ * @return Pointer to the first matching attribute, or NULL if no match was found.
+ */
 struct attr *
 attr_search(struct attr **attrs, struct attr *last, enum attr_type attr)
 {
@@ -448,6 +514,32 @@ attr_match(enum attr_type search, enum attr_type found)
 	}
 }
 
+/**
+ * @brief Generic get function
+ *
+ * This function searches an attribute list for an attribute of a given type and
+ * stores it in the attr parameter. If no match is found in attrs and the
+ * def_attrs argument is supplied, def_attrs is searched for the attribute type
+ * and the first match (if any) is returned.
+ * <p>
+ * Searching for attr_any or attr_any_xml is supported, but def_attrs will not
+ * be searched in that case.
+ * <p>
+ * An iterator can be specified to get multiple attributes of the same type:
+ * The first call will return the first match from attr; each subsequent call
+ * with the same iterator will return the next match. After obtaining the last
+ * match from attr, def_attrs is searched in the same manner. If no more matching
+ * attributes are found in either of them, false is returned.
+ *
+ * @param attrs Points to the array of attribute pointers to be searched
+ * @param def_attrs Points to a list of pointers to default attributes.
+ * If an attribute is not found in attrs, the function will return the first
+ * match from def_attrs. This parameter may be NULL.
+ * @param type The attribute type to search for
+ * @param attr Points to a {@code struct attr} which will receive the attribute
+ * @param iter An iterator. This parameter may be NULL.
+ * @return True if a matching attribute was found, false if not.
+ */
 int
 attr_generic_get_attr(struct attr **attrs, struct attr **def_attrs, enum attr_type type, struct attr *attr, struct attr_iter *iter)
 {
@@ -475,6 +567,18 @@ attr_generic_get_attr(struct attr **attrs, struct attr **def_attrs, enum attr_ty
 	return 0;
 }
 
+/**
+ * @brief Generic set function
+ *
+ * This function will search the list for the first attribute of the same type
+ * as the supplied new one and replace it with that. If the list does not
+ * contain an attribute whose type matches that of the new one, the new
+ * attribute is inserted into the list.
+ *
+ * @param attrs Points to the array of attribute pointers to be updated
+ * @param attr The new attribute.
+ * @return Pointer to the updated attribute list
+ */
 struct attr **
 attr_generic_set_attr(struct attr **attrs, struct attr *attr)
 {
@@ -498,6 +602,15 @@ attr_generic_set_attr(struct attr **attrs, struct attr *attr)
 	return curr;
 }
 
+/**
+ * @brief Generic add function
+ *
+ * This function will insert a new attribute into the list.
+ *
+ * @param attrs Points to the array of attribute pointers to be updated
+ * @param attr The new attribute.
+ * @return Pointer to the updated attribute list
+ */
 struct attr **
 attr_generic_add_attr(struct attr **attrs, struct attr *attr)
 {
@@ -823,12 +936,12 @@ attr_from_line(char *line, char *name, int *pos, char *val_ret, char *name_ret)
 }
 
 /**
- * Check if an enumeration of attribute types contains a specific attribute.
+ * @brief Checks if an enumeration of attribute types contains a specific attribute.
  *
- * @param types Pointer to the attr_type enumeration to be searched
+ * @param types Points to a NULL-terminated array of pointers to {@code enum attr_type}, which will be searched
  * @param type The attr_type to be searched for
  *
- * @return 1 if the attribute type was found, 0 if it was not found or if a null pointer was passed as types
+ * @return True if the attribute type was found, false if it was not found or if {@code types} is empty
  */
 int
 attr_types_contains(enum attr_type *types, enum attr_type type)
@@ -842,14 +955,16 @@ attr_types_contains(enum attr_type *types, enum attr_type type)
 }
 
 /**
- * Check if an enumeration of attribute types contains a specific attribute. 
- * It is different from attr_types_contains in that it returns a caller-defined value if the pointer to the enumeration is NULL.
+ * @brief Check if an enumeration of attribute types contains a specific attribute.
+ *
+ * This function is mostly identical to {@code attr_types_contains()} but returns the supplied default
+ * value if {@code types} is empty.
  *
- * @param types Pointer to the attr_type enumeration to be searched
+ * @param types Points to a NULL-terminated array of pointers to {@code enum attr_type}, which will be searched
  * @param type The attr_type to be searched for
- * @param deflt The default value to return if types is NULL.
+ * @param deflt The default value to return if {@code types} is empty.
  *
- * @return 1 if the attribute type was found, 0 if it was not found, the value of the deflt argument if types is NULL.
+ * @return True if the attribute type was found, false if it was not found, {@code deflt} if types is empty.
  */
 int
 attr_types_contains_default(enum attr_type *types, enum attr_type type, int deflt)
diff --git a/navit/attr_def.h b/navit/attr_def.h
index 412587873..b2666ae8e 100644
--- a/navit/attr_def.h
+++ b/navit/attr_def.h
@@ -1,4 +1,4 @@
-/**
+/*
  * Navit, a modular navigation system.
  * Copyright (C) 2005-2009 Navit Team
  *
@@ -17,6 +17,15 @@
  * Boston, MA  02110-1301, USA.
  */
 
+/** @file attr_def.h
+ * @brief Attribute definitions.
+ * 
+ * Any attribute used by a Navit object must be defined in this file.
+ *
+ * @author Navit Team
+ * @date 2005-2014
+ */
+
 /* prototypes */
 
 /* common */
diff --git a/navit/log.c b/navit/log.c
index 60ae5c385..2373f1954 100644
--- a/navit/log.c
+++ b/navit/log.c
@@ -1,4 +1,4 @@
-/**
+/*
  * Navit, a modular navigation system.
  * Copyright (C) 2005-2008 Navit Team
  *
@@ -16,6 +16,15 @@
  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  * Boston, MA  02110-1301, USA.
  */
+ 
+/** @file log.c
+ * @brief The log object.
+ * 
+ * This file implements everything needed for logging: the log object and its functions.
+ *
+ * @author Navit Team
+ * @date 2005-2014
+ */
 
 #include "config.h"
 #ifdef HAVE_UNISTD_H
@@ -67,6 +76,17 @@ struct log {
 	struct log_data trailer;
 };
 
+/** 
+ * @brief Stores formatted time to a string.
+ *
+ * This function obtains local system time, formats it as specified in {@code fmt} and stores it in buffer.
+ * Format strings follow the same syntax as those for {@code strftime()}.
+ *
+ * @param buffer A preallocated buffer that will receive the formatted time
+ * @param size Size of the buffer, in bytes
+ * @param fmt The format string
+ * @return Nothing
+ */
 static void
 strftime_localtime(char *buffer, int size, char *fmt)
 {
@@ -76,8 +96,19 @@ strftime_localtime(char *buffer, int size, char *fmt)
 	t=time(NULL);
 	tm=localtime(&t);
 	strftime(buffer, 4096, fmt, tm);
+	//FIXME: strftime(buffer, size - 1, fmt, tm);
 }
 
+/** 
+ * @brief Expands placeholders in a filename
+ *
+ * This function examines the {@code log->filename} and replaces any placeholders
+ * found in it with date, time or an incremental number. If an incremental number is specified, the function
+ * will ensure the filename is unique. The expanded filename will be stored {@code log->filename_ex2}.
+ * The function uses {@code log->filename_ex1} to store the partly-expanded filename.
+ * 
+ * @param this_ The log object.
+ */
 static void
 expand_filenames(struct log *this_)
 {
@@ -102,6 +133,13 @@ expand_filenames(struct log *this_)
 		this_->filename_ex2=g_strdup(this_->filename_ex1);
 }
 
+/** 
+ * @brief Sets the time at which the log buffer was last flushed.
+ *
+ * This function sets {@code log->last_flush} to current time.
+ *
+ * @param this_ The log object.
+ */
 static void
 log_set_last_flush(struct log *this_)
 {
@@ -110,6 +148,24 @@ log_set_last_flush(struct log *this_)
 #endif
 }
 
+/** 
+ * @brief Opens a log file.
+ *
+ * This function opens the log file for {@code log}.
+ * The file name must be specified by {@code log->filename_ex2} before this function is called.
+ * <p>
+ * {@code log->overwrite} specifies the behavior if the file exists: if true,
+ * an existing file will be overwritten, else it will be appended to.
+ * <p>
+ * If the directory specified in the filename does not exist and the {@code log->mkdir}
+ * is true, it will be created.
+ * <p>
+ * After the function returns, {@code log->f} will contain the file handle (or NULL, if
+ * the operation failed) and {@code log->empty} will indicate if the file is empty.
+ * {@code log->last_flush} will be updated with the current time.
+ *
+ * @param this_ The log object.
+ */
 static void
 log_open(struct log *this_)
 {
@@ -131,6 +187,13 @@ log_open(struct log *this_)
 	log_set_last_flush(this_);
 }
 
+/** 
+ * @brief Closes a log file.
+ *
+ * This function writes the trailer to a log file, flushes it and closes the log file for {@code log}.
+ *
+ * @param this_ The log object.
+ */
 static void
 log_close(struct log *this_)
 {
@@ -143,6 +206,31 @@ log_close(struct log *this_)
 	this_->f=NULL;
 }
 
+/** 
+ * @brief Flushes the buffer of a log.
+ *
+ * This function writes buffered log data to the log file associated with {@code log}
+ * and updates {@code log->last_flush} with the current time.
+ * <p>
+ * If {@code log->lazy} is true, this function will open the file if needed, else
+ * the file must be opened with {@code log_open()} prior to calling this function.
+ * <p>
+ * If the file is empty, the header will be written first, followed by the buffer data.
+ * {@code log->empty} will be set to zero if header or data are written to the file.
+ *
+ * @param this_ The log object.
+ * @param flags Flags to control behavior of the function:
+ * <br>
+ * {@code log_flag_replace_buffer}: ignored
+ * <br>
+ * {@code log_flag_force_flush}: ignored
+ * <br>
+ * {@code log_flag_keep_pointer}: keeps the file pointer at the start position of the new data
+ * <br>
+ * {@code log_flag_keep_buffer}: prevents clearing of the buffer after a successful write (default is to clear the buffer).
+ * <br>
+ * {@code log_flag_truncate}: truncates the log file at the current position. On the Win32 Base API, this flag has no effect.
+ */
 static void
 log_flush(struct log *this_, enum log_flags flags)
 {
@@ -185,13 +273,39 @@ log_flush(struct log *this_, enum log_flags flags)
 	log_set_last_flush(this_);
 }
 
+/** 
+ * @brief Determines if the maximum buffer size of a log has been exceeded.
+ *
+ * This function examines the size of the data buffer to determine if it exceeds
+ * the maximum size specified in {@code log->flush_size} and thus needs to be flushed.
+ *
+ * @param this_ The log object.
+ * @return True if the cache needs to be flushed, false otherwise.
+ */
 static int
 log_flush_required(struct log *this_)
 {
 	return this_->data.len > this_->flush_size;
 }
 
-
+/** 
+ * @brief Rotates a log file.
+ *
+ * This function rotates a log by stopping and immediately restarting it.
+ * Stopping flushes the buffer and closes the file; restarting determines the
+ * new file name and opens the file as needed (depending on the lazy member).
+ * <p>
+ * Depending on the file name format and how the function was called, a new log
+ * file will be created or the old log file will be reused (appended to or
+ * overwritten, depending on {@code log->overwrite}): if the file name includes an
+ * incremental number, the new file will always have a different name. If a
+ * previous call to {@code log_change_required()} returned true, the new file
+ * will also have a different name. In all other cases the new file will have
+ * the same name as the old one, causing the old file to be overwritten or
+ * appended to.
+ *
+ * @param this_ The log object.
+ */
 static void
 log_change(struct log *this_)
 {
@@ -202,6 +316,15 @@ log_change(struct log *this_)
 		log_open(this_);
 }
 
+/** 
+ * @brief Determines if the log must be rotated.
+ *
+ * This function expands the date and time placeholders in {@code log->filename}
+ * to determine if the resulting part of the filename has changed.
+ *
+ * @param this_ The log object.
+ * @return True if the date/time-dependent part of the filename has changed, false otherwise.
+ */
 static int
 log_change_required(struct log *this_)
 {
@@ -211,6 +334,14 @@ log_change_required(struct log *this_)
 	return (strcmp(this_->filename_ex1, buffer) != 0);
 }
 
+/** 
+ * @brief Determines if the flush interval of a log has elapsed and flushes the buffer if needed.
+ *
+ * This function calculates the difference between current time and {@code log->last_flush}.
+ * If it is greater than or equal to {@code log->flush_time}, the buffer is flushed.
+ *
+ * @param this_ The log object.
+ */
 static void
 log_timer(struct log *this_)
 {
@@ -225,6 +356,15 @@ log_timer(struct log *this_)
 #endif
 }
 
+/** 
+ * @brief Gets an attribute
+ *
+ * @param this_ The log object.
+ * @param attr_type The attribute type to return
+ * @param attr Points to a struct attr to store the attribute
+ * @param iter An attribute iterator
+ * @return True for success, false for failure
+ */
 int
 log_get_attr(struct log *this_, enum attr_type type, struct attr *attr, struct attr_iter *iter)
 {
@@ -232,6 +372,13 @@ log_get_attr(struct log *this_, enum attr_type type, struct attr *attr, struct a
 }
 
 
+/** 
+ * @brief Creates and initializes a new log object.
+ *
+ * @param parent The parent object.
+ * @param attrs Points to an array of pointers to attributes for the new log object
+ * @return The new log object, or NULL if creation fails.
+ */
 struct log *
 log_new(struct attr * parent,struct attr **attrs)
 {
@@ -285,6 +432,16 @@ log_new(struct attr * parent,struct attr **attrs)
 	return ret;
 }
 
+/** 
+ * @brief Sets the header for a log file.
+ *
+ * This function sets the header, which is to be inserted into any log file before
+ * the actual log data.
+ *
+ * @param this_ The log object.
+ * @param data The header data.
+ * @param len Size of the header data to be copied, in bytes.
+ */
 void
 log_set_header(struct log *this_, char *data, int len)
 {
@@ -293,6 +450,16 @@ log_set_header(struct log *this_, char *data, int len)
 	memcpy(this_->header.data, data, len);
 }
 
+/** 
+ * @brief Sets the trailer for a log file.
+ *
+ * This function sets the trailer, which is to be added to any log file after
+ * the actual log data.
+ *
+ * @param this_ The log object.
+ * @param data The trailer data.
+ * @param len Size of the trailer data to be copied, in bytes.
+ */
 void
 log_set_trailer(struct log *this_, char *data, int len)
 {
@@ -301,6 +468,28 @@ log_set_trailer(struct log *this_, char *data, int len)
 	memcpy(this_->trailer.data, data, len);
 }
 
+/** 
+ * @brief Writes to a log.
+ *
+ * This function appends data to a log. It rotates the log, if needed, before 
+ * adding the new data. After adding, the log is flushed if the buffer exceeds
+ * its maximum size or if the {@code log_flag_force_flush} flag is set.
+ *
+ * @param this_ The log object.
+ * @param data Points to a buffer containing the data to be appended.
+ * @param len Length of the data to be appended, in bytes.
+ * @param flags Flags to control behavior of the function:
+ * <br>
+ * {@code log_flag_replace_buffer}: discards any data in the buffer not yet written to the log file
+ * <br>
+ * {@code log_flag_force_flush}: forces a flush of the log after appending the data
+ * <br>
+ * {code log_flag_keep_pointer}: ignored
+ * <br>
+ * {@code log_flag_keep_buffer}: ignored
+ * <br>
+ * {@code log_flag_truncate}: ignored
+ */
 void
 log_write(struct log *this_, char *data, int len, enum log_flags flags)
 {
@@ -313,7 +502,7 @@ log_write(struct log *this_, char *data, int len, enum log_flags flags)
 		this_->data.len=0;
 	if (this_->data.len + len > this_->data.max_len) {
 		dbg(2,"overflow\n");
-		this_->data.max_len+=16384;
+		this_->data.max_len+=16384; // FIXME: what if len exceeds this->data.max_len by more than 16384 bytes?
 		this_->data.data=g_realloc(this_->data.data,this_->data.max_len);
 	}
 	memcpy(this_->data.data+this_->data.len, data, len);
@@ -322,6 +511,14 @@ log_write(struct log *this_, char *data, int len, enum log_flags flags)
 		log_flush(this_, flags);
 }
 
+/** 
+ * @brief Returns the data buffer of a log object and its length.
+ *
+ * @param this_ The log object.
+ * @param len Points to an int which will receive the length of the buffer.
+ * This can be NULL, in which case no information on buffer length will be stored.
+ * @return Pointer to the data buffer.
+ */
 void *
 log_get_buffer(struct log *this_, int *len)
 {
@@ -331,6 +528,16 @@ log_get_buffer(struct log *this_, int *len)
 }
 
 
+/** 
+ * @brief Writes a formatted string to a log.
+ *
+ * This function formats a string in a fashion similar to {@code printf()} and related functions
+ * and writes it to a log using {@code log_write()}.
+ *
+ * @param this_ The log object.
+ * @param fmt The format string.
+ * @param ... Additional arguments must be specified for each placeholder in the format string.
+ */
 void
 log_printf(struct log *this_, char *fmt, ...)
 {
@@ -347,6 +554,11 @@ log_printf(struct log *this_, char *fmt, ...)
 	va_end(ap);
 }
 
+/** 
+ * @brief Destroys a log object and frees up its memory.
+ *
+ * @param this_ The log object.
+ */
 void
 log_destroy(struct log *this_)
 {
diff --git a/navit/osd/core/osd_core.c b/navit/osd/core/osd_core.c
index 9aadd9c3a..525f3d011 100644
--- a/navit/osd/core/osd_core.c
+++ b/navit/osd/core/osd_core.c
@@ -2516,13 +2516,14 @@ struct osd_text {
 
 
 /**
- * @brief Format a text attribute
+ * @brief Formats a text attribute
  *
  * Returns the formatted current value of an attribute as a string
  * 
- * @param attr Pointer to an attr structure specifying the attribute to be formatted
- * @param format Pointer to a string specifying how to format the attribute. Allowed format strings depend on the attribute; this member can be NULL.
- * @returns Pointer to a string containing the formatted value
+ * @param attr The attribute to be formatted
+ * @param format A string specifying how to format the attribute. Allowed format strings depend on the attribute; this member can be NULL.
+ * @param imperial True to convert values to imperial, false to return metric values
+ * @returns The formatted value
  */
 static char *
 osd_text_format_attr(struct attr *attr, char *format, int imperial)
@@ -2675,11 +2676,17 @@ osd_text_format_attr(struct attr *attr, char *format, int imperial)
 }
 
 /**
- * Parse a string of the form key.subkey or key[index].subkey into its components, where subkey can itself have its own index and further subkeys
+ * @brief Parses a string of the form key.subkey or key[index].subkey into its components, where subkey
+ * can itself have its own index and further subkeys
  *
- * @param in String to parse (the part before subkey will be modified by the function); upon returning this pointer will point to a string containing key
- * @param index Pointer to an address that will receive a pointer to a string containing index or a null pointer if key does not have an index
- * @returns If the function succeeds, a pointer to a string containing subkey, i.e. everything following the first period, or a pointer to an empty string if there is nothing left to parse. If the function fails(index with missing closed bracket or passing a null pointer as index argument when an index was encountered), the return value is NULL
+ * @param in String to parse (the part before subkey will be modified by the function); upon returning
+ * this pointer will point to a string containing key
+ * @param index Pointer to an address that will receive a pointer to a string containing index or NULL
+ * if key does not have an index
+ * @returns If the function succeeds, a pointer to a string containing subkey, i.e. everything following
+ * the first period, or a pointer to an empty string if there is nothing left to parse. If the function
+ * fails (index with missing closed bracket or passing a null pointer as index argument when an index
+ * was encountered), the return value is NULL
  */
 static char *
 osd_text_split(char *in, char **index)
@@ -2944,10 +2951,11 @@ osd_text_draw(struct osd_priv_common *opc, struct navit *navit, struct vehicle *
 }
 
 /**
- * @brief Create a new osd_text_item and insert it into a linked list
+ * @brief Creates a new osd_text_item and inserts it into a linked list
  * 
- * @param parent Pointer to the preceding osd_text_item structure in the list. If NULL, the new osd_text_item becomes the root element of a new list.
- * @returns A pointer to the new osd_text_item element.
+ * @param parent The preceding {@code osd_text_item} in the list. If NULL, the new item becomes the root
+ * element of a new list
+ * @returns The new {@code osd_text_item}
  */
 static struct osd_text_item *
 oti_new(struct osd_text_item * parent)
@@ -2967,13 +2975,14 @@ oti_new(struct osd_text_item * parent)
 }
 
 /**
- * @brief Prepare a text type OSD element
+ * @brief Prepares a text type OSD element
  *
- * Parses the label string (as specified in the XML file) for a text type OSD element into attributes and static text. 
+ * This function parses the label string (as specified in the XML file) for a text type OSD element
+ * into attributes and static text.
  * 
- * @param this Pointer to an osd_text structure representing the OSD element. The items member of this structure will receive a pointer to a list of osd_text_item structures.
- * @param nav Pointer to a navit structure
- * @returns nothing
+ * @param opc The {@code struct osd_priv_common} for the OSD element. {@code opc->data->items} will
+ * receive a pointer to a list of {@code osd_text_item} structures.
+ * @param nav The navit structure
  */
 static void
 osd_text_prepare(struct osd_priv_common *opc, struct navit *nav)
diff --git a/navit/util.c b/navit/util.c
index e18799f01..1859d38b1 100644
--- a/navit/util.c
+++ b/navit/util.c
@@ -184,17 +184,15 @@ char *stristr(const char *String, const char *Pattern)
 
 #ifndef HAVE_GETDELIM
 /**
- * Read the part of a file up to a delimiter to a string.
+ * @brief Reads the part of a file up to a delimiter to a string.
  * <p> 
- * Read up to (and including) a DELIMITER from FP into *LINEPTR (and
-   NUL-terminate it).  
- * @param lineptr Pointer to a pointer returned from malloc (or
-   NULL), pointing to a buffer. It is realloc'ed as
-   necessary and will receive the data read.
+ * Read up to (and including) a DELIMITER from FP into *LINEPTR (and NUL-terminate it).
+ *
+ * @param lineptr Pointer to a pointer returned from malloc (or NULL), pointing to a buffer. It is
+ * realloc'ed as necessary and will receive the data read.
  * @param n Size of the buffer.  
  *
- * @return Number of characters read (not including
-   the null terminator), or -1 on error or EOF.
+ * @return Number of characters read (not including the null terminator), or -1 on error or EOF.
 */
 ssize_t
 getdelim (char **lineptr, size_t *n, int delimiter, FILE *fp)
@@ -312,11 +310,11 @@ int gettimeofday(struct timeval *time, void *local)
 }
 #endif
 /**
- * Convert an ISO 8601-style time string into epoch time.
+ * @brief Converts an ISO 8601-style time string into epoch time.
  *
- * @param iso8601 Pointer to a string containing the time in ISO 8601 format.
+ * @param iso8601 Time in ISO 8601 format.
  *
- * @return An unsigned integer representing the number of seconds elapsed since January 1, 1970, 00:00:00 UTC.
+ * @return The number of seconds elapsed since January 1, 1970, 00:00:00 UTC.
  */
 unsigned int
 iso8601_to_secs(char *iso8601)
@@ -347,9 +345,9 @@ iso8601_to_secs(char *iso8601)
 }
 
 /**
- * Output local system time in ISO 8601 format.
+ * @brief Outputs local system time in ISO 8601 format.
  *
- * @return Pointer to a string containing the time in ISO 8601 format
+ * @return Time in ISO 8601 format
  */
 char *
 current_to_iso8601(void)
diff --git a/navit/vehicle.c b/navit/vehicle.c
index 48ee8af39..a0cc27721 100644
--- a/navit/vehicle.c
+++ b/navit/vehicle.c
@@ -1,4 +1,4 @@
-/**
+/*
  * Navit, a modular navigation system.
  * Copyright (C) 2005-2009 Navit Team
  *
@@ -16,6 +16,16 @@
  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  * Boston, MA  02110-1301, USA.
  */
+ 
+/** @file vehicle.c
+ * @brief Generic components of the vehicle object.
+ * 
+ * This file implements the generic vehicle interface, i.e. everything which is
+ * not specific to a single data source.
+ *
+ * @author Navit Team
+ * @date 2005-2014
+ */
 
 #include <stdio.h>
 #include <string.h>
@@ -78,7 +88,13 @@ static int vehicle_add_log(struct vehicle *this_, struct log *log);
 
 
 /**
- * Creates a new vehicle
+ * @brief Creates a new vehicle
+ *
+ * @param parent
+ * @param attrs Points to a null-terminated array of pointers to the attributes
+ * for the new vehicle type.
+ *
+ * @return The newly created vehicle object
  */
 struct vehicle *
 vehicle_new(struct attr *parent, struct attr **attrs)
@@ -138,7 +154,7 @@ vehicle_new(struct attr *parent, struct attr **attrs)
 }
 
 /**
- * Destroys a vehicle
+ * @brief Destroys a vehicle
  * 
  * @param this_ The vehicle to destroy
  */
@@ -188,8 +204,9 @@ vehicle_attr_iter_destroy(struct attr_iter *iter)
  *
  * @param this_ Pointer to a vehicle structure
  * @param type The attribute type to look for
- * @param attr Pointer to an attr structure to store the attribute
+ * @param attr Pointer to a {@code struct attr} to store the attribute
  * @param iter A vehicle attr_iter
+ * @return True for success, false for failure
  */
 int
 vehicle_get_attr(struct vehicle *this_, enum attr_type type, struct attr *attr, struct attr_iter *iter)
@@ -210,9 +227,9 @@ vehicle_get_attr(struct vehicle *this_, enum attr_type type, struct attr *attr,
 /**
  * Generic set function
  *
- * @param this_ Pointer to a vehicle structure
- * @param attr Pointer to an attr structure for the attribute to be set
- * @return nonzero on success, zero on failure
+ * @param this_ A vehicle
+ * @param attr The attribute to set
+ * @return False on success, true on failure
  */
 int
 vehicle_set_attr(struct vehicle *this_, struct attr *attr)
@@ -237,7 +254,9 @@ vehicle_set_attr(struct vehicle *this_, struct attr *attr)
  * Generic add function
  *
  * @param this_ A vehicle
- * @param attr A struct attr
+ * @param attr The attribute to add
+ *
+ * @return true if the attribute was added, false if not.
  */
 int
 vehicle_add_attr(struct vehicle *this_, struct attr *attr)
@@ -452,10 +471,10 @@ vehicle_draw_do(struct vehicle *this_, int lazy)
 }
 
 /**
- * Writes to an NMEA log.
+ * @brief Writes to an NMEA log.
  *
- * @param this_ Pointer to the vehicle structure of the data source
- * @param log Pointer to a log structure for the log file
+ * @param this_ The vehicle supplying data
+ * @param log The log to write to
  */
 static void
 vehicle_log_nmea(struct vehicle *this_, struct log *log)
@@ -468,6 +487,15 @@ vehicle_log_nmea(struct vehicle *this_, struct log *log)
 	log_write(log, pos_attr.u.str, strlen(pos_attr.u.str), 0);
 }
 
+/**
+ * Add a tag to the extensions section of a GPX trackpoint.
+ *
+ * @param tag The tag to add
+ * @param logstr Pointer to a pointer to a string to be inserted into the log.
+ * When calling this function, {@code *logstr} must point to the substring into which the new tag is
+ * to be inserted. If {@code *logstr} is NULL, a new string will be created for the extensions section.
+ * Upon returning, {@code *logstr} will point to the new string with the additional tag inserted.
+ */
 void
 vehicle_log_gpx_add_tag(char *tag, char **logstr)
 {
@@ -502,10 +530,10 @@ vehicle_log_gpx_add_tag(char *tag, char **logstr)
 }
 
 /**
- * Writes to a GPX log.
+ * @brief Writes a trackpoint to a GPX log.
  *
- * @param this_ Pointer to the vehicle structure of the data source
- * @param log Pointer to a log structure for the log file
+ * @param this_ The vehicle supplying data
+ * @param log The log to write to
  */
 static void
 vehicle_log_gpx(struct vehicle *this_, struct log *log)
@@ -580,10 +608,10 @@ vehicle_log_gpx(struct vehicle *this_, struct log *log)
 }
 
 /**
- * Writes to a text log.
+ * @brief Writes to a text log.
  *
- * @param this_ Pointer to the vehicle structure of the data source
- * @param log Pointer to a log structure for the log file
+ * @param this_ The vehicle supplying data
+ * @param log The log to write to
  */
 static void
 vehicle_log_textfile(struct vehicle *this_, struct log *log)
@@ -604,10 +632,10 @@ vehicle_log_textfile(struct vehicle *this_, struct log *log)
 }
 
 /**
- * Writes to a binary log.
+ * @brief Writes to a binary log.
  *
- * @param this_ Pointer to the vehicle structure of the data source
- * @param log Pointer to a log structure for the log file
+ * @param this_ The vehicle supplying data
+ * @param log The log to write to
  */
 static void
 vehicle_log_binfile(struct vehicle *this_, struct log *log)
@@ -664,10 +692,12 @@ vehicle_log_binfile(struct vehicle *this_, struct log *log)
 }
 
 /**
- * Register a new log to receive data.
+ * @brief Registers a new log to receive data.
+ *
+ * @param this_ The vehicle supplying data
+ * @param log The log to write to
  *
- * @param this_ Pointer to the vehicle structure of the data source
- * @param log Pointer to a log structure for the log file
+ * @return False if the log is of an unknown type, true otherwise (including when {@code attr_type} is missing).
  */
 static int
 vehicle_add_log(struct vehicle *this_, struct log *log)
diff --git a/navit/vehicle/android/vehicle_android.c b/navit/vehicle/android/vehicle_android.c
index 758ea913b..166786906 100644
--- a/navit/vehicle/android/vehicle_android.c
+++ b/navit/vehicle/android/vehicle_android.c
@@ -59,7 +59,7 @@ struct vehicle_priv {
 /**
  * @brief Free the android_vehicle
  * 
- * @param priv
+ * @param priv vehicle_priv structure for the vehicle
  * @returns nothing
  */
 static void
@@ -70,12 +70,12 @@ vehicle_android_destroy(struct vehicle_priv *priv)
 }
 
 /**
- * @brief Provide the outside with information
- * 
- * @param priv
- * @param type TODO: What can this be?
- * @param attr
- * @returns true/false
+ * @brief Retrieves a vehicle attribute.
+ *
+ * @param priv vehicle_priv structure for the vehicle
+ * @param type The attribute type to retrieve
+ * @param attr Points to an attr structure that will receive the attribute data
+ * @returns True for success, false for failure
  */
 static int
 vehicle_android_position_attr_get(struct vehicle_priv *priv,
diff --git a/navit/vehicle/wince/vehicle_wince.c b/navit/vehicle/wince/vehicle_wince.c
index 9a26d2522..1f3f42f43 100644
--- a/navit/vehicle/wince/vehicle_wince.c
+++ b/navit/vehicle/wince/vehicle_wince.c
@@ -710,6 +710,11 @@ vehicle_wince_disable_watch(struct vehicle_priv *priv)
 }
 
 
+/**
+ * @brief Frees the wince_vehicle
+ * 
+ * @param priv vehicle_priv structure for the vehicle
+ */
 static void
 vehicle_wince_destroy(struct vehicle_priv *priv)
 {
@@ -729,6 +734,14 @@ vehicle_wince_destroy(struct vehicle_priv *priv)
 	g_free(priv);
 }
 
+/**
+ * @brief Retrieves a vehicle attribute.
+ *
+ * @param priv vehicle_priv structure for the vehicle
+ * @param type The attribute type to retrieve
+ * @param attr Points to an attr structure that will receive the attribute data
+ * @returns True for success, false for failure
+ */
 static int
 vehicle_wince_position_attr_get(struct vehicle_priv *priv,
 			       enum attr_type type, struct attr *attr)
@@ -846,6 +859,14 @@ struct vehicle_methods vehicle_wince_methods = {
 	NULL,
 };
 
+/**
+ * @brief Creates a new wince_vehicle
+ * 
+ * @param meth
+ * @param cbl
+ * @param attrs
+ * @returns vehicle_priv
+ */
 static struct vehicle_priv *
 vehicle_wince_new(struct vehicle_methods
 		      *meth, struct callback_list
@@ -921,6 +942,9 @@ vehicle_wince_new(struct vehicle_methods
 	return NULL;
 }
 
+/**
+ * @brief Registers the vehicle_wince plugin
+ */
 void
 plugin_init(void)
 {