From 7591838644a3fcb5145b9ccc7200166debe7ba87 Mon Sep 17 00:00:00 2001 From: Romain Forlot Date: Fri, 17 Mar 2017 12:48:46 +0100 Subject: Comments fixes, typo and formating. No more warning when generate the docs and all comments follow the same formating. Change-Id: I80d4c5c2d64401c2e53a550c60155680c4f968ce Signed-off-by: Romain Forlot --- src/utils/openxc-utils.cpp | 174 ++++++++++++++++++++++----------------------- src/utils/signals.cpp | 44 ++++++------ src/utils/timer.cpp | 1 + src/utils/timer.hpp | 29 +++----- 4 files changed, 119 insertions(+), 129 deletions(-) (limited to 'src/utils') diff --git a/src/utils/openxc-utils.cpp b/src/utils/openxc-utils.cpp index 111ac1d3..52b49d29 100644 --- a/src/utils/openxc-utils.cpp +++ b/src/utils/openxc-utils.cpp @@ -20,17 +20,17 @@ #include "../configuration.hpp" -/** - * @brief Build a specific VehicleMessage containing a DiagnosticResponse. - * - * @param[in] request - Original request use to retrieve decoder and callback - * @param[in] response - Response to the request that will be decoded if decoder set - * and put into the DiagnosticResponse of the VehicleMessage. - * @param[in] parsed_value - raw parsed value of the payload from CAN message - * - * @return a vehicle message including simple message that will be convert into - * a JSON object before being pushed to the subscribers - */ +/// +/// @brief Build a specific VehicleMessage containing a DiagnosticResponse. +/// +/// @param[in] request - Original request use to retrieve decoder and callback +/// @param[in] response - Response to the request that will be decoded if decoder set +/// and put into the DiagnosticResponse of the VehicleMessage. +/// @param[in] parsed_value - raw parsed value of the payload from CAN message +/// +/// @return a vehicle message including simple message that will be convert into +/// a JSON object before being pushed to the subscribers +/// openxc_VehicleMessage build_VehicleMessage(active_diagnostic_request_t* request, const DiagnosticResponse& response, float parsed_value) { openxc_VehicleMessage message; @@ -85,14 +85,14 @@ openxc_VehicleMessage build_VehicleMessage(active_diagnostic_request_t* request, return message; } -/** - * @brief Build a specific VehicleMessage containing a SimpleMessage. - * - * @param[in] message - simple message to include into openxc_VehicleMessage - * - * @return a vehicle message including simple message that will be convert into - * a JSON object before being pushed to the subscribers - */ +/// +/// @brief Build a specific VehicleMessage containing a SimpleMessage. +/// +/// @param[in] message - simple message to include into openxc_VehicleMessage +/// +/// @return a vehicle message including simple message that will be convert into +/// a JSON object before being pushed to the subscribers +/// openxc_VehicleMessage build_VehicleMessage(const openxc_SimpleMessage& message) { openxc_VehicleMessage v; @@ -107,12 +107,12 @@ openxc_VehicleMessage build_VehicleMessage(const openxc_SimpleMessage& message) return v; } -/** - * @brief Build an empty VehicleMessage that isn't usable by at least the struct - * is initialized for the most part and can be use to check a false return value. - * - * @return A VehicleMessage with all boolean value to false. - */ +/// +/// @brief Build an empty VehicleMessage that isn't usable by at least the struct +/// is initialized for the most part and can be use to check a false return value. +/// +/// @return A VehicleMessage with all boolean value to false. +/// openxc_VehicleMessage build_VehicleMessage() { openxc_VehicleMessage v; @@ -134,17 +134,17 @@ bool is_valid(const openxc_VehicleMessage& v) return true; } -/** - * @brief Build an openxc_SimpleMessage associating a name to an openxc_DynamicField - * - * @param[in] name - const string reference name to assign to the created SimpleMessage - * this will set has_name member to true and assign name to the name member. Maximum size for name is - * set to 100 char. - * @param[in] value - const reference with DynamicField to assign to SimpleMessage - * value. - * - * @return an openxc_SimpleMessage struct initialized with name and value provided. - */ +/// +/// @brief Build an openxc_SimpleMessage associating a name to an openxc_DynamicField +/// +/// @param[in] name - const string reference name to assign to the created SimpleMessage +/// this will set has_name member to true and assign name to the name member. Maximum size for name is +/// set to 100 char. +/// @param[in] value - const reference with DynamicField to assign to SimpleMessage +/// value. +/// +/// @return an openxc_SimpleMessage struct initialized with name and value provided. +/// openxc_SimpleMessage build_SimpleMessage(const std::string& name, const openxc_DynamicField& value) { openxc_SimpleMessage s; @@ -157,14 +157,14 @@ openxc_SimpleMessage build_SimpleMessage(const std::string& name, const openxc_D return s; } -/** - * @brief Build an openxc_DynamicField with a string value - * - * @param[in] value - const string reference value to assign to builded - * openxc_DynamicField. - * - * @return openxc_DynamicField initialized with a string value. - */ +/// +/// @brief Build an openxc_DynamicField with a string value +/// +/// @param[in] value - const string reference value to assign to builded +/// openxc_DynamicField. +/// +/// @return openxc_DynamicField initialized with a string value. +/// openxc_DynamicField build_DynamicField(const std::string& value) { openxc_DynamicField d; @@ -179,15 +179,15 @@ openxc_DynamicField build_DynamicField(const std::string& value) return d; } -/** - * @fn openxc_DynamicField build_DynamicField(double value); - * - * @brief Build an openxc_DynamicField with a double value - * - * @param[in] value - double value to assign to builded openxc_DynamicField. - * - * @return openxc_DynamicField initialized with a double value. - */ +/// +/// @fn openxc_DynamicField build_DynamicField(double value); +/// +/// @brief Build an openxc_DynamicField with a double value +/// +/// @param[in] value - double value to assign to builded openxc_DynamicField. +/// +/// @return openxc_DynamicField initialized with a double value. +/// openxc_DynamicField build_DynamicField(double value) { openxc_DynamicField d; @@ -202,13 +202,13 @@ openxc_DynamicField build_DynamicField(double value) return d; } -/** - * @brief Build an openxc_DynamicField with a boolean value - * - * @param[in] value - boolean value to assign to builded openxc_DynamicField. - * - * @return openxc_DynamicField initialized with a boolean value. - */ +/// +/// @brief Build an openxc_DynamicField with a boolean value +/// +/// @param[in] value - boolean value to assign to builded openxc_DynamicField. +/// +/// @return openxc_DynamicField initialized with a boolean value. +/// openxc_DynamicField build_DynamicField(bool value) { openxc_DynamicField d; @@ -223,16 +223,16 @@ openxc_DynamicField build_DynamicField(bool value) return d; } -/** - * @brief Extract the simple message value from an openxc_VehicleMessage - * and return it. If there isn't SimpleMessage in the VehicleMessage then - * returned value will be a SimpleMessage with all field set at false. - * DynamicField from SimpleMessage will be boolean DynamicField set to false too. - * - * @param[in] v_msg - const reference to openxc_VehicleMessage - * - * @return A simpleMessage from the provided VehicleMessage. - */ +/// +/// @brief Extract the simple message value from an openxc_VehicleMessage +/// and return it. If there isn't SimpleMessage in the VehicleMessage then +/// returned value will be a SimpleMessage with all field set at false. +/// DynamicField from SimpleMessage will be boolean DynamicField set to false too. +/// +/// @param[in] v_msg - const reference to openxc_VehicleMessage +/// +/// @return A simpleMessage from the provided VehicleMessage. +/// openxc_SimpleMessage get_simple_message(const openxc_VehicleMessage& v_msg) { if (v_msg.has_simple_message) @@ -242,13 +242,13 @@ openxc_SimpleMessage get_simple_message(const openxc_VehicleMessage& v_msg) return s_msg; } -/** - * @brief Make a JSON object from a DynamicField - * - * @param[in] field - openxc_DynamicField struct to convert into - * a json object. - * @param[out] value - pointer to the object to set up. - */ +/// +/// @brief Make a JSON object from a DynamicField +/// +/// @param[in] field - openxc_DynamicField struct to convert into +/// a json object. +/// @param[out] value - pointer to the object to set up. +/// void jsonify_DynamicField(const openxc_DynamicField& field, json_object* value) { if(field.has_numeric_value) @@ -259,16 +259,16 @@ void jsonify_DynamicField(const openxc_DynamicField& field, json_object* value) json_object_object_add(value, "value", json_object_new_string(field.string_value)); } -/** - * @brief Make a JSON object from a SimpleMessage - * - * @param[in] s_msg - const reference to an openxc_SimpleMessage - * struct to convert into a json object. - * @param[out] json - pointer with the DynamicField converted into json object - * - * @return True if SimpleMessage has been transformed into json object - * and false if not. In such case, a json object is returned { "error": "error msg"} - */ +/// +/// @brief Make a JSON object from a SimpleMessage +/// +/// @param[in] s_msg - const reference to an openxc_SimpleMessage +/// struct to convert into a json object. +/// @param[out] json - pointer with the DynamicField converted into json object +/// +/// @return True if SimpleMessage has been transformed into json object +/// and false if not. In such case, a json object is returned { "error": "error msg"} +/// bool jsonify_simple(const openxc_SimpleMessage& s_msg, json_object* json) { if(s_msg.has_name) diff --git a/src/utils/signals.cpp b/src/utils/signals.cpp index 41e13c08..2e14a98f 100644 --- a/src/utils/signals.cpp +++ b/src/utils/signals.cpp @@ -17,21 +17,21 @@ #include "signals.hpp" -/** - * @brief Can signal event map making access to afb_event - * externaly to an openxc existing structure. - * - * @desc Event map is making relation between can_signal_t generic name - * and the afb_event struct used by application framework to pushed - * to the subscriber. - */ +/// +/// @brief Can signal event map making access to afb_event +/// externaly to an openxc existing structure. +/// +/// Event map is making relation between can_signal_t generic name +/// and the afb_event struct used by application framework to pushed +/// to the subscriber. +/// std::map subscribed_signals; -/** -* @brief Mutex allowing safe manipulation on subscribed_signals map. -* @desc To ensure that the map object isn't modified when we read it, you -* have to set this mutex before use subscribed_signals map object. -*/ +/// +/// @brief Mutex allowing safe manipulation on subscribed_signals map. +/// To ensure that the map object isn't modified when we read it, you +/// have to set this mutex before use subscribed_signals map object. +/// std::mutex subscribed_signals_mutex; std::mutex& get_subscribed_signals_mutex() @@ -44,15 +44,15 @@ std::map& get_subscribed_signals() return subscribed_signals; } -/** - * @fn std::vector find_signals(const openxc_DynamicField &key) - * @brief return signals name found searching through CAN_signals and OBD2 pid - * - * @param[in] const openxc_DynamicField : can contain numeric or string value in order to search against - * can signals or obd2 signals name. - * - * @return std::vector Vector of signals name found. - */ +/// +/// @fn std::vector find_signals(const openxc_DynamicField &key) +/// @brief return signals name found searching through CAN_signals and OBD2 pid +/// +/// @param[in] key : can contain numeric or string value in order to search against +/// can signals or obd2 signals name. +/// +/// @return Vector of signals name found. +/// std::vector find_signals(const openxc_DynamicField &key) { std::vector found_signals_name; diff --git a/src/utils/timer.cpp b/src/utils/timer.cpp index 784bb46a..7c2560e3 100644 --- a/src/utils/timer.cpp +++ b/src/utils/timer.cpp @@ -60,6 +60,7 @@ frequency_clock_t::frequency_clock_t(float frequency) {} /// @brief Return the period in ms given the frequency in hertz. +/// @param[in] frequency - Frequency to convert, in Hertz float frequency_clock_t::frequency_to_period(float frequency) { return 1 / frequency; diff --git a/src/utils/timer.hpp b/src/utils/timer.hpp index b34fdf64..5be0e3cd 100644 --- a/src/utils/timer.hpp +++ b/src/utils/timer.hpp @@ -17,35 +17,24 @@ #pragma once -/* - * @brief return epoch in milliseconds - * - * @return long long int epoch in milliseconds - */ +/// @brief return epoch in milliseconds +/// +/// @return long long int epoch in milliseconds typedef long long int (*time_function_t)(); long long int system_time_us(); long long int system_time_ms(); long long int system_time_s(); -/** - * @class frequency_clock_t - * @brief A frequency counting clock. - * - * @var frequency_clock_t::frequency - * the clock frequency in Hz. - * @var frequency_clock_t::last_time - * the last time (in milliseconds since startup) that the clock - * ticked. - * @var frequency_clock_t::time_function - * a function returning current time - */ + +/// @brief A frequency counting clock. +/// Utility class allowing some time function. class frequency_clock_t { private: - float frequency_; - unsigned long last_tick_; - time_function_t time_function_; + float frequency_; ///< the clock frequency in Hz. + unsigned long last_tick_; ///< the last time (in milliseconds since startup) that the clock ticked. + time_function_t time_function_; ///< a function returning current time public: frequency_clock_t(); -- cgit 1.2.3-korg