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 | 0142c41c20b67ae69148b3b9a2d1904ab0ff4a0d (patch) | |
tree | ec89aeb02a56d632789e690b30f68acfab094177 /navit/vehicle.c | |
parent | 65153cf2bf3dac6c5c71ff7b940fa44c2d05f854 (diff) | |
download | navit-svn-0142c41c20b67ae69148b3b9a2d1904ab0ff4a0d.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/vehicle.c')
-rw-r--r-- | navit/vehicle.c | 76 |
1 files changed, 53 insertions, 23 deletions
diff --git a/navit/vehicle.c b/navit/vehicle.c index 48ee8af3..a0cc2772 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) |