Comments, Cleanup, format

Change-Id: I9f032cc232e77ce73e889a1656f1ad86cfdec774
Signed-off-by: Romain Forlot <romain.forlot@iot.bzh>

7 files changed, 66 insertions, 49 deletions

diff --git a/CAN-binder/low-can-binding/can/can-bus.cpp b/CAN-binder/low-can-binding/can/can-bus.cpp
index d06eb77c..e481a1bd 100644
--- a/CAN-binder/low-can-binding/can/can-bus.cpp
+++ b/CAN-binder/low-can-binding/can/can-bus.cpp
@@ -40,6 +40,14 @@ can_bus_t::can_bus_t(utils::config_parser_t conf_file)
 	: conf_file_{conf_file}
 {}
 
+/// @brief Take a decoded message to determine if its value comply with the wanted
+/// filtering values.
+///
+/// @param[in] vehicle_message - A decoded message to analyze
+/// @param[in] can_subscription - the subscription which will be notified depending
+///  on its filtering values. Filtering values are stored in the event_filtermember.
+///
+/// @return True if the value is compliant with event filter values, false if not...
 bool can_bus_t::apply_filter(const openxc_VehicleMessage& vehicle_message, std::shared_ptr<low_can_subscription_t> can_subscription)
 {
 	bool send = false;
@@ -283,12 +291,8 @@ void can_bus_t::push_new_vehicle_message(int subscription_id, const openxc_Vehic
 	vehicle_message_q_.push(std::make_pair(subscription_id, v_msg));
 }
 
-/// @brief Return the shared pointer on the can_bus_dev_t initialized 
-/// with device_name "bus"
-///
-/// @param[in] bus - CAN bus device name to retrieve.
-///
-/// @return A shared pointer on an object can_bus_dev_t
+/// @brief Fills the CAN device map member with value from device
+/// mapping configuration file read at initialization.
 void can_bus_t::set_can_devices()
 {
 	can_devices_ = conf_file_.get_devices_name();
@@ -300,6 +304,9 @@ void can_bus_t::set_can_devices()
 	}
 }
 
+
+/// @brief Return the CAN device index from the map
+/// map are sorted so index depend upon alphabetical sorting.
 int can_bus_t::get_can_device_index(const std::string& bus_name) const
 {
 	int i = 0;
@@ -312,6 +319,9 @@ int can_bus_t::get_can_device_index(const std::string& bus_name) const
 	return i;
 }
 
+/// @brief Return CAN device name from a logical CAN device name gotten from
+/// the signals.json description file which comes from a CAN databases file in
+/// general.
 const std::string can_bus_t::get_can_device_name(const std::string& id_name) const
 {
 	std::string ret;
diff --git a/CAN-binder/low-can-binding/can/can-bus.hpp b/CAN-binder/low-can-binding/can/can-bus.hpp
index b19519a8..a76d3e87 100644
--- a/CAN-binder/low-can-binding/can/can-bus.hpp
+++ b/CAN-binder/low-can-binding/can/can-bus.hpp
@@ -72,7 +72,7 @@ private:
 	std::mutex decoded_can_message_mutex_;  ///< mutex protecting the vehicle_message_q_ queue.
 	std::queue <std::pair<int, openxc_VehicleMessage> > vehicle_message_q_; ///< queue that'll store openxc_VehicleMessage to pushed
 
-	std::vector<std::pair<std::string, std::string> > can_devices_;
+	std::vector<std::pair<std::string, std::string> > can_devices_; ///< can_devices_ - holds a mapping between logical CAN devices names and linux CAN devices names.
 public:
 	explicit can_bus_t(utils::config_parser_t conf_file);
 	can_bus_t(can_bus_t&&);
diff --git a/CAN-binder/low-can-binding/can/can-message-definition.hpp b/CAN-binder/low-can-binding/can/can-message-definition.hpp
index 3e150369..6d0f17d6 100644
--- a/CAN-binder/low-can-binding/can/can-message-definition.hpp
+++ b/CAN-binder/low-can-binding/can/can-message-definition.hpp
@@ -35,22 +35,24 @@
 
 class can_message_set_t;
 
+/// @brief The definition of a CAN message. This includes a lot of metadata, so
+///  to save memory this class gets the can_signal_t object related to a CAN message.
 class can_message_definition_t
 {
 private:
-	can_message_set_t* parent_; /*!< parent_ - Pointer to the CAN message set holding this CAN message definition */
-	std::string bus_; /*!< bus_ - Address of CAN bus device. */
-	uint32_t id_; /*!< id_ - The ID of the message.*/
-	can_message_format_t format_; /*!< format_ - the format of the message's ID.*/
-	frequency_clock_t frequency_clock_; /*!<  clock_ - an optional frequency clock to control the output of this
-							*      message, if sent raw, or simply to mark the max frequency for custom
-							*      handlers to retrieve.*/
-	bool force_send_changed_; /*!< force_send_changed_ - If true, regardless of the frequency, it will send CAN
-							*	message if it has changed when using raw passthrough.*/
-	std::vector<uint8_t> last_value_; /*!< last_value_ - The last received value of the message. Defaults to undefined.
-										*	This is required for the forceSendChanged functionality, as the stack
-										*	needs to compare an incoming CAN message with the previous frame.*/
-	std::vector<std::shared_ptr<can_signal_t> > can_signals_; /*!< can_signals_ - Vector holding can_signal_t object which share the same arbitration ID */
+	can_message_set_t* parent_; ///< parent_ - Pointer to the CAN message set holding this CAN message definition */
+	std::string bus_; ///< bus_ - Address of CAN bus device. */
+	uint32_t id_; ///< id_ - The ID of the message.*/
+	can_message_format_t format_; ///< format_ - the format of the message's ID.*/
+	frequency_clock_t frequency_clock_; ///<  clock_ - an optional frequency clock to control the output of this
+							///      message, if sent raw, or simply to mark the max frequency for custom
+							///      handlers to retrieve.*/
+	bool force_send_changed_; ///< force_send_changed_ - If true, regardless of the frequency, it will send CAN
+							///	message if it has changed when using raw passthrough.*/
+	std::vector<uint8_t> last_value_; ///< last_value_ - The last received value of the message. Defaults to undefined.
+										///	This is required for the forceSendChanged functionality, as the stack
+										///	needs to compare an incoming CAN message with the previous frame.*/
+	std::vector<std::shared_ptr<can_signal_t> > can_signals_; ///< can_signals_ - Vector holding can_signal_t object which share the same arbitration ID */
 
 public:
 	//can_message_definition_t(const can_message_definition_t& b);
diff --git a/CAN-binder/low-can-binding/can/can-message-set.cpp b/CAN-binder/low-can-binding/can/can-message-set.cpp
index a41f0085..c31dec62 100644
--- a/CAN-binder/low-can-binding/can/can-message-set.cpp
+++ b/CAN-binder/low-can-binding/can/can-message-set.cpp
@@ -52,6 +52,7 @@ std::vector<std::shared_ptr<can_signal_t> > can_message_set_t::get_all_can_signa
 	return can_signals;
 }
 
+/// @brief Return vector holding all diagnostic messages definitions handled by this message set.
 std::vector<std::shared_ptr<diagnostic_message_t> >& can_message_set_t::get_diagnostic_messages()
 {
 	return diagnostic_messages_;
diff --git a/CAN-binder/low-can-binding/can/can-message-set.hpp b/CAN-binder/low-can-binding/can/can-message-set.hpp
index c763de6d..2a7cb53c 100644
--- a/CAN-binder/low-can-binding/can/can-message-set.hpp
+++ b/CAN-binder/low-can-binding/can/can-message-set.hpp
@@ -27,8 +27,8 @@ class can_signal_t;
 class can_message_definition_t;
 class diagnostic_message_t;
 
-/// @brief A parent wrapper for a particular set of CAN messages and associated
-/// CAN buses(e.g. a vehicle or program).
+/// @brief A parent wrapper for a particular set of CAN messages and diagnostic messages 
+/// (e.g. a vehicle or program).
 class can_message_set_t
 {
 private:
diff --git a/CAN-binder/low-can-binding/can/can-message.cpp b/CAN-binder/low-can-binding/can/can-message.cpp
index 93894947..10b3232c 100644
--- a/CAN-binder/low-can-binding/can/can-message.cpp
+++ b/CAN-binder/low-can-binding/can/can-message.cpp
@@ -84,7 +84,7 @@ bool can_message_t::get_rtr_flag_() const
 ///
 /// @brief Retrieve format_ member value.
 ///
-/// @return format_ class member
+/// @return format_ class member. Default to INVALID.
 ///
 can_message_format_t can_message_t::get_format() const
 {
@@ -149,12 +149,10 @@ void can_message_t::set_timestamp(uint64_t timestamp)
 	timestamp_ = timestamp;
 }
 
-///
 /// @brief Control whether the object is correctly initialized
 ///  to be sent over the CAN bus
 ///
-/// @return true if object correctly initialized and false if not.
-///
+/// @return True if object correctly initialized and false if not.
 bool can_message_t::is_correct_to_send()
 {
 	if (id_ != 0 && length_ != 0 && format_ != can_message_format_t::INVALID)
@@ -167,14 +165,12 @@ bool can_message_t::is_correct_to_send()
 	return false;
 }
 
-///
 /// @brief Set format_ member value.
 ///
 /// Preferred way to initialize these members by using
 /// convert_from_canfd_frame method.
 ///
 /// @param[in] new_format - class member
-///
 void can_message_t::set_format(const can_message_format_t new_format)
 {
 	if(new_format == can_message_format_t::STANDARD || new_format == can_message_format_t::EXTENDED || new_format == can_message_format_t::INVALID)
@@ -191,7 +187,6 @@ void can_message_t::set_format(const can_message_format_t new_format)
 /// @param[in] nbytes - bytes read from socket read operation.
 ///
 /// @return A can_message_t object fully initialized with canfd_frame values.
-///
 can_message_t can_message_t::convert_from_frame(const struct canfd_frame& frame, size_t nbytes, uint64_t timestamp)
 {
 	uint8_t maxdlen, length, flags = (uint8_t)NULL;
@@ -272,6 +267,14 @@ can_message_t can_message_t::convert_from_frame(const struct canfd_frame& frame,
 	return can_message_t(maxdlen, id, length, format, rtr_flag, flags, data, timestamp);
 }
 
+/// @brief Take a can_frame struct to initialize class members
+///
+/// This is the preferred way to initialize class members.
+///
+/// @param[in] frame - can_frame to convert coming from a read of CAN socket
+/// @param[in] nbytes - bytes read from socket read operation.
+///
+/// @return A can_message_t object fully initialized with can_frame values.
 can_message_t can_message_t::convert_from_frame(const struct can_frame& frame, size_t nbytes, uint64_t timestamp)
 {
 	uint8_t maxdlen, length, flags = (uint8_t)NULL;
@@ -343,13 +346,11 @@ can_message_t can_message_t::convert_from_frame(const struct can_frame& frame, s
 	return can_message_t(maxdlen, id, length, format, rtr_flag, flags, data, timestamp);
 }
 
-///
 /// @brief Take all initialized class's members and build an
 /// canfd_frame struct that can be use to send a CAN message over
 /// the bus.
 ///
 /// @return canfd_frame struct built from class members.
-///
 struct canfd_frame can_message_t::convert_to_canfd_frame()
 {
 	canfd_frame frame;
@@ -366,6 +367,11 @@ struct canfd_frame can_message_t::convert_to_canfd_frame()
 	return frame;
 }
 
+/// @brief Take all initialized class's members and build an
+/// can_frame struct that can be use to send a CAN message over
+/// the bus.
+///
+/// @return can_frame struct built from class members.
 struct can_frame can_message_t::convert_to_can_frame()
 {
 	can_frame frame;
diff --git a/CAN-binder/low-can-binding/can/can-message.hpp b/CAN-binder/low-can-binding/can/can-message.hpp
index ced2602a..b206ebdb 100644
--- a/CAN-binder/low-can-binding/can/can-message.hpp
+++ b/CAN-binder/low-can-binding/can/can-message.hpp
@@ -31,28 +31,26 @@
  * @brief The ID format for a CAN message.
  */
 enum class can_message_format_t {
-	STANDARD, /*!< STANDARD - standard 11-bit CAN arbitration ID. */
-	EXTENDED, /*!< EXTENDED - an extended frame, with a 29-bit arbitration ID. */
-	INVALID,    /*!< INVALID - INVALID code used at initialization to signify that it isn't usable'*/
+	STANDARD, ///< STANDARD - standard 11-bit CAN arbitration ID. */
+	EXTENDED, ///< EXTENDED - an extended frame, with a 29-bit arbitration ID. */
+	INVALID,    ///< INVALID - INVALID code used at initialization to signify that it isn't usable'*/
 };
 
-/**
- * @class can_message_t
- *
- * @brief A compact representation of a single CAN message, meant to be used in in/out
- * buffers.
- */
+/// @class can_message_t
+///
+/// @brief A compact representation of a single CAN message, meant to be used in in/out
+/// buffers. It is a wrapper of a can_frame struct with some sugar around it for binding purposes.
 class can_message_t {
 private:
-	uint8_t maxdlen_; /*!< maxdlen_ - Max data length deduce from number of bytes read from the socket.*/
-	uint32_t id_; /*!< id_ - The ID of the message. */
-	uint8_t length_; /*!< length_ - the length of the data array (max 8). */
-	can_message_format_t format_; /*!< format_ - the format of the message's ID.*/
-	bool rtr_flag_; /*!< rtr_flag_ - Telling if the frame has RTR flag positionned. Then frame hasn't data field*/
-	uint8_t flags_; /*!< flags_ - flags of a CAN FD frame. Needed if we catch FD frames.*/
-	std::vector<uint8_t> data_; /*!< data_ - The message's data field with a size of 8 which is the standard about CAN bus messages.*/
-	uint64_t timestamp_; /*!< timestamp_ - timestamp of the received message*/
-	int sub_id_; /*!< sub_id_ - Subscription index. */
+	uint8_t maxdlen_; ///< maxdlen_ - Max data length deduce from number of bytes read from the socket.*/
+	uint32_t id_; ///< id_ - The ID of the message. */
+	uint8_t length_; ///< length_ - the length of the data array (max 8). */
+	can_message_format_t format_; ///< format_ - the format of the message's ID.*/
+	bool rtr_flag_; ///< rtr_flag_ - Telling if the frame has RTR flag positionned. Then frame hasn't data field*/
+	uint8_t flags_; ///< flags_ - flags of a CAN FD frame. Needed if we catch FD frames.*/
+	std::vector<uint8_t> data_; ///< data_ - The message's data field with a size of 8 which is the standard about CAN bus messages.*/
+	uint64_t timestamp_; ///< timestamp_ - timestamp of the received message*/
+	int sub_id_; ///< sub_id_ - Subscription index. */
 
 public:
 	can_message_t();