diff options
author | mvglasow <mvglasow@ffa7fe5e-494d-0410-b361-a75ebd5db220> | 2014-11-15 16:50:21 +0000 |
---|---|---|
committer | mvglasow <mvglasow@ffa7fe5e-494d-0410-b361-a75ebd5db220> | 2014-11-15 16:50:21 +0000 |
commit | bab28ff2c621410fdc7ea08e8ac444b660d9b539 (patch) | |
tree | ec89aeb02a56d632789e690b30f68acfab094177 /navit | |
parent | e23cc5b467250b9098ee41455675789f51bdfa85 (diff) | |
download | navit-bab28ff2c621410fdc7ea08e8ac444b660d9b539.tar.gz |
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
Diffstat (limited to 'navit')
-rw-r--r-- | navit/attr.c | 135 | ||||
-rw-r--r-- | navit/attr_def.h | 11 | ||||
-rw-r--r-- | navit/log.c | 218 | ||||
-rw-r--r-- | navit/osd/core/osd_core.c | 41 | ||||
-rw-r--r-- | navit/util.c | 24 | ||||
-rw-r--r-- | navit/vehicle.c | 76 | ||||
-rw-r--r-- | navit/vehicle/android/vehicle_android.c | 14 | ||||
-rw-r--r-- | navit/vehicle/wince/vehicle_wince.c | 24 |
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) { |