Improve Doxygen comments and formating.

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

8 files changed, 189 insertions, 173 deletions

diff --git a/src/can/can-bus-dev.cpp b/src/can/can-bus-dev.cpp
index a574b42d..dd2f51f7 100644
--- a/src/can/can-bus-dev.cpp
+++ b/src/can/can-bus-dev.cpp
@@ -204,9 +204,14 @@ int can_bus_dev_t::send(can_message_t& can_msg)
 	return 0;
 }
 
-/// @brief Send a can message from a can_message_t object.
-/// @param[in] can bus used to send the message
-/// @param[in] can_msg the can message object to send
+/// @brief Static method used to send diagnostic CAN message
+/// that follow isotp SendShimsMessage signature. This method is launched
+/// from diagnostic manager's' same name method. It will use the diagnostic
+/// manager configured CAN bus device to send the CAN message.
+///
+/// @param[in] arbitration_id - CAN arbitration id.
+/// @param[in] data - CAN message payload to send
+/// @param[in] size - size of the data to send
 bool can_bus_dev_t::shims_send(const uint32_t arbitration_id, const uint8_t* data, const uint8_t size)
 {
 	ssize_t nbytes;
diff --git a/src/can/can-bus.cpp b/src/can/can-bus.cpp
index 6483fd9c..09fce46d 100644
--- a/src/can/can-bus.cpp
+++ b/src/can/can-bus.cpp
@@ -50,7 +50,18 @@ can_bus_t::can_bus_t(int conf_file)
 {
 }
 
-
+/**
+ * @brief Will make the decoding operation on a classic CAN message. It will not
+ * handle CAN commands nor diagnostic messages that have their own method to get
+ * this happens.
+ *
+ * It will add to the vehicle_message queue the decoded message and tell the event push
+ * thread to process it.
+ *
+ * @param[in] can_message - a single CAN message from the CAN socket read, to be decode.
+ *
+ * @return How many signals has been decoded.
+ */
 int can_bus_t::process_can_signals(can_message_t& can_message)
 {
 	int processed_signals = 0;
@@ -92,13 +103,23 @@ int can_bus_t::process_can_signals(can_message_t& can_message)
 	return processed_signals;
 }
 
+/**
+ * @brief Will make the decoding operation on a diagnostic CAN message.It will add to
+ * the vehicle_message queue the decoded message and tell the event push thread to process it.
+ *
+ * @param[in] entry - an active_diagnostic_request_t object that made the request
+ * about that diagnostic CAN message.
+ * @param[in] can_message - a single CAN message from the CAN socket read, to be decode.
+ *
+ * @return How many signals has been decoded.
+ */
 int can_bus_t::process_diagnostic_signals(active_diagnostic_request_t* entry, const can_message_t& can_message)
 {
 	int processed_signals = 0;
 	openxc_VehicleMessage vehicle_message;
 
 	diagnostic_manager_t& manager = configuration_t::instance().get_diagnostic_manager();
-	
+
 	std::lock_guard<std::mutex> subscribed_signals_lock(get_subscribed_signals_mutex());
 	std::map<std::string, struct afb_event>& s = get_subscribed_signals();
 
@@ -141,7 +162,7 @@ int can_bus_t::process_diagnostic_signals(active_diagnostic_request_t* entry, co
 *  corresponding decoding function if there is one assigned for that signal. If not, it will be the default
 *  noopDecoder function that will operate on it.
 *
-*  Depending on the nature of message, if id match a diagnostic request corresponding id for a response 
+*  Depending on the nature of message, if id match a diagnostic request corresponding id for a response
 *  then decoding a diagnostic message else use classic CAN signals decoding functions.
 *
 *  TODO: make diagnostic messages parsing optionnal.
@@ -195,9 +216,9 @@ void can_bus_t::can_event_push()
 }
 
 /**
-	* @brief Will initialize threads that will decode
-	*  and push subscribed events.
-	*/
+* @brief Will initialize threads that will decode
+*  and push subscribed events.
+*/
 void can_bus_t::start_threads()
 {
 	is_decoding_ = true;
@@ -224,7 +245,11 @@ void can_bus_t::stop_threads()
 
 /**
 * @brief Will initialize can_bus_dev_t objects after reading
-* the configuration file passed in the constructor.
+* the configuration file passed in the constructor. All CAN buses
+* Initialized here will be added to a vector holding them for
+* inventory and later access.
+*
+* That will initialize CAN socket reading too using a new thread.
 */
 int can_bus_t::init_can_dev()
 {
diff --git a/src/can/can-bus.hpp b/src/can/can-bus.hpp
index b4f1a3ee..97b683d7 100644
--- a/src/can/can-bus.hpp
+++ b/src/can/can-bus.hpp
@@ -66,7 +66,7 @@ private:
 
 	std::condition_variable new_decoded_can_message_; /// < condition_variable use to wait until there is a new vehicle message to read from the queue vehicle_message_q_
 	std::mutex decoded_can_message_mutex_;  /// < mutex protecting the vehicle_message_q_ queue.
-	std::queue <openxc_VehicleMessage> vehicle_message_q_; /// < queue that'll store openxc_VehicleMessage to pushed 
+	std::queue <openxc_VehicleMessage> vehicle_message_q_; /// < queue that'll store openxc_VehicleMessage to pushed
 
 	std::vector<std::shared_ptr<can_bus_dev_t>> can_devices_; /// < Can device map containing all can_bus_dev_t objects initialized during init_can_dev function
 
@@ -93,4 +93,3 @@ public:
 
 	const std::vector<std::shared_ptr<can_bus_dev_t>>& get_can_devices() const;
 };
-
diff --git a/src/can/can-command.hpp b/src/can/can-command.hpp
index 062cbd75..8324d324 100644
--- a/src/can/can-command.hpp
+++ b/src/can/can-command.hpp
@@ -53,14 +53,3 @@ typedef struct {
 	CommandHandler handler; /*!< handler - An function to process the received command's data and perform some
  							 *	action.*/
 } CanCommand;
-
-/* Public: Return an array of all OpenXC CAN commands enabled in the active
- * configuration that can write back to CAN with a custom handler.
- *
- * Commands not defined here are handled using a 1-1 mapping from the signals
- * list.
- */
-CanCommand* getCommands();
-
-/* Public: Return the length of the array returned by getCommandCount(). */
-int getCommandCount();
\ No newline at end of file
diff --git a/src/can/can-decoder.cpp b/src/can/can-decoder.cpp
index a5e4d8ee..ec31e367 100644
--- a/src/can/can-decoder.cpp
+++ b/src/can/can-decoder.cpp
@@ -19,6 +19,15 @@
 #include "canutil/read.h"
 #include "../utils/openxc-utils.hpp"
 
+/* Public: Parse the signal's bitfield from the given data and return the raw
+* value.
+*
+* @param[in] signal - The signal to parse from the data.
+* @param[in] message - can_message_t to parse
+*
+* @return Returns the raw value of the signal parsed as a bitfield from the given byte
+* array.
+*/
 float decoder_t::parseSignalBitfield(can_signal_t& signal, const can_message_t& message)
 {
 	 return bitfield_parse_float(message.get_data(), CAN_MESSAGE_SIZE,
@@ -26,6 +35,21 @@ float decoder_t::parseSignalBitfield(can_signal_t& signal, const can_message_t&
 			signal.get_offset());
 }
 
+/* Public: Wrap a raw CAN signal value in a DynamicField without modification.
+*
+* This is an implementation of the SignalDecoder type signature, and can be
+* used directly in the can_signal_t.decoder field.
+*
+* @param[in] signal  - The details of the signal that contains the state mapping.
+* @param[in] signals - The list of all signals
+* @param[in] value - The numerical value that will be wrapped in a DynamicField.
+* @param[out]send - An output argument that will be set to false if the value should
+*     not be sent for any reason.
+*
+* @return Returns a DynamicField with the original, unmodified raw CAN signal value as
+* its numeric value. The 'send' argument will not be modified as this decoder
+* always succeeds.
+*/
 openxc_DynamicField decoder_t::noopDecoder(can_signal_t& signal,
 		const std::vector<can_signal_t>& signals, float value, bool* send)
 {
@@ -33,7 +57,21 @@ openxc_DynamicField decoder_t::noopDecoder(can_signal_t& signal,
 
 	return decoded_value;
 }
-
+/* Public: Coerces a numerical value to a boolean.
+*
+* This is an implementation of the SignalDecoder type signature, and can be
+* used directly in the can_signal_t.decoder field.
+*
+* @param[in] signal  - The details of the signal that contains the state mapping.
+* @param[in] signals - The list of all signals
+* @param[in] value - The numerical value that will be converted to a boolean.
+* @param[out] send - An output argument that will be set to false if the value should
+*     not be sent for any reason.
+*
+* @return Returns a DynamicField with a boolean value of false if the raw signal value
+* is 0.0, otherwise true. The 'send' argument will not be modified as this
+* decoder always succeeds.
+*/
 openxc_DynamicField decoder_t::booleanDecoder(can_signal_t& signal,
 		const std::vector<can_signal_t>& signals, float value, bool* send)
 {
@@ -41,18 +79,48 @@ openxc_DynamicField decoder_t::booleanDecoder(can_signal_t& signal,
 
 	return decoded_value;
 }
-
+/* Public: Update the metadata for a signal and the newly received value.
+*
+* This is an implementation of the SignalDecoder type signature, and can be
+* used directly in the can_signal_t.decoder field.
+*
+* This function always flips 'send' to false.
+*
+* @param[in] signal  - The details of the signal that contains the state mapping.
+* @param[in] signals - The list of all signals.
+* @param[in] value - The numerical value that will be converted to a boolean.
+* @param[out] send - This output argument will always be set to false, so the caller will
+*      know not to publish this value to the pipeline.
+*
+* @return Return value is undefined.
+*/
 openxc_DynamicField decoder_t::ignoreDecoder(can_signal_t& signal,
 		const std::vector<can_signal_t>& signals, float value, bool* send)
 {
 	if(send)
 	  *send = false;
-	
-	openxc_DynamicField decoded_value = {0, openxc_DynamicField_Type_BOOL, 0, "", 0, 0, 0, 0};
-	
+
+	openxc_DynamicField decoded_value;
+
 	return decoded_value;
 }
 
+/* Public: Find and return the corresponding string state for a CAN signal's
+* raw integer value.
+*
+* This is an implementation of the SignalDecoder type signature, and can be
+* used directly in the can_signal_t.decoder field.
+*
+* @param[in] signal  - The details of the signal that contains the state mapping.
+* @param[in] signals - The list of all signals.
+* @param[in] value - The numerical value that should map to a state.
+* @param[out] send - An output argument that will be set to false if the value should
+*     not be sent for any reason.
+*
+* @return Returns a DynamicField with a string value if a matching state is found in
+* the signal. If an equivalent isn't found, send is sent to false and the
+* return value is undefined.
+*/
 openxc_DynamicField decoder_t::stateDecoder(can_signal_t& signal,
 		const std::vector<can_signal_t>& signals, float value, bool* send)
 {
@@ -66,6 +134,20 @@ openxc_DynamicField decoder_t::stateDecoder(can_signal_t& signal,
 	return decoded_value;
 }
 
+
+/* Public: Parse a signal from a CAN message, apply any required transforations
+*      to get a human readable value and public the result to the pipeline.
+*
+* If the can_signal_t has a non-NULL 'decoder' field, the raw CAN signal value
+* will be passed to the decoder before publishing.
+*
+* @param[in] signal - The details of the signal to decode and forward.
+* @param[in] message - The received CAN message that should contain this signal.
+* @param[in] signals - an array of all active signals.
+*
+* The decoder returns an openxc_DynamicField, which may contain a number,
+* string or boolean.
+*/
 openxc_DynamicField decoder_t::translateSignal(can_signal_t& signal, can_message_t& message,
 	const std::vector<can_signal_t>& signals)
 {
@@ -89,6 +171,21 @@ openxc_DynamicField decoder_t::translateSignal(can_signal_t& signal, can_message
 	return decoded_value;
 }
 
+/* Public: Parse a signal from a CAN message and apply any required
+* transforations to get a human readable value.
+*
+* If the can_signal_t has a non-NULL 'decoder' field, the raw CAN signal value
+* will be passed to the decoder before returning.
+*
+* @param[in] signal - The details of the signal to decode and forward.
+* @param[in] value - The numerical value that will be converted to a boolean.
+* @param[in] signals - an array of all active signals.
+* @param[out] send - An output parameter that will be flipped to false if the value could
+*      not be decoded.
+*
+* @return The decoder returns an openxc_DynamicField, which may contain a number,
+* string or boolean. If 'send' is false, the return value is undefined.
+*/
 openxc_DynamicField decoder_t::decodeSignal( can_signal_t& signal,
 		float value, const std::vector<can_signal_t>& signals, bool* send)
 {
@@ -99,6 +196,19 @@ openxc_DynamicField decoder_t::decodeSignal( can_signal_t& signal,
 	return decoded_value;
 }
 
+/* Public: Decode a transformed, human readable value from an raw CAN signal
+* already parsed from a CAN message.
+*
+* This is the same as decodeSignal but you must parse the bitfield value of the signal from the CAN
+* message yourself. This is useful if you need that raw value for something
+* else.
+*
+* @param[in] signal - The details of the signal to decode and forward.
+* @param[in] value - The numerical value that will be converted to a boolean.
+* @param[in] signals - an array of all active signals.
+* @param[out] send - An output parameter that will be flipped to false if the value could
+*      not be decoded.
+*/
 openxc_DynamicField decoder_t::decodeSignal( can_signal_t& signal,
 		const can_message_t& message, const std::vector<can_signal_t>& signals, bool* send)
 {
diff --git a/src/can/can-decoder.hpp b/src/can/can-decoder.hpp
index 63d91d4e..326a2b73 100644
--- a/src/can/can-decoder.hpp
+++ b/src/can/can-decoder.hpp
@@ -21,139 +21,24 @@
 
 class decoder_t
 {
-	public:
-		/* Public: Parse the signal's bitfield from the given data and return the raw
-		* value.
-		*
-		* signal - The signal to parse from the data.
-		* data - The data to parse the signal from.
-		* length - The length of the data array.
-		*
-		* Returns the raw value of the signal parsed as a bitfield from the given byte
-		* array.
-		*/
-		static float parseSignalBitfield(can_signal_t& signal, const can_message_t& message);
-
-		/* Public: Find and return the corresponding string state for a CAN signal's
-		* raw integer value.
-		*
-		* This is an implementation of the SignalDecoder type signature, and can be
-		* used directly in the can_signal_t.decoder field.
-		*
-		* signal  - The details of the signal that contains the state mapping.
-		* signals - The list of all signals.
-		* signalCount - the length of the signals array.
-		* value - The numerical value that should map to a state.
-		* send - An output argument that will be set to false if the value should
-		*     not be sent for any reason.
-		*
-		* Returns a DynamicField with a string value if a matching state is found in
-		* the signal. If an equivalent isn't found, send is sent to false and the
-		* return value is undefined.
-		*/
-		static openxc_DynamicField stateDecoder(can_signal_t& signal, const std::vector<can_signal_t>& signals,
-				float value, bool* send);
-
-		/* Public: Coerces a numerical value to a boolean.
-		*
-		* This is an implementation of the SignalDecoder type signature, and can be
-		* used directly in the can_signal_t.decoder field.
-		*
-		* signal  - The details of the signal that contains the state mapping.
-		* signals - The list of all signals
-		* signalCount - The length of the signals array
-		* value - The numerical value that will be converted to a boolean.
-		* send - An output argument that will be set to false if the value should
-		*     not be sent for any reason.
-		*
-		* Returns a DynamicField with a boolean value of false if the raw signal value
-		* is 0.0, otherwise true. The 'send' argument will not be modified as this
-		* decoder always succeeds.
-		*/
-		static openxc_DynamicField booleanDecoder(can_signal_t& signal, const std::vector<can_signal_t>& signals,
-				float value, bool* send);
-
-		/* Public: Update the metadata for a signal and the newly received value.
-		*
-		* This is an implementation of the SignalDecoder type signature, and can be
-		* used directly in the can_signal_t.decoder field.
-		*
-		* This function always flips 'send' to false.
-		*
-		* signal  - The details of the signal that contains the state mapping.
-		* signals - The list of all signals.
-		* signalCount - The length of the signals array.
-		* value - The numerical value that will be converted to a boolean.
-		* send - This output argument will always be set to false, so the caller will
-		*      know not to publish this value to the pipeline.
-		*
-		* The return value is undefined.
-		*/
-		static openxc_DynamicField ignoreDecoder(can_signal_t& signal, const std::vector<can_signal_t>& signals,
-				float value, bool* send);
-
-		/* Public: Wrap a raw CAN signal value in a DynamicField without modification.
-		*
-		* This is an implementation of the SignalDecoder type signature, and can be
-		* used directly in the can_signal_t.decoder field.
-		*
-		* signal  - The details of the signal that contains the state mapping.
-		* signals - The list of all signals
-		* signalCount - The length of the signals array
-		* value - The numerical value that will be wrapped in a DynamicField.
-		* send - An output argument that will be set to false if the value should
-		*     not be sent for any reason.
-		*
-		* Returns a DynamicField with the original, unmodified raw CAN signal value as
-		* its numeric value. The 'send' argument will not be modified as this decoder
-		* always succeeds.
-		*/
-		static openxc_DynamicField noopDecoder(can_signal_t& signal, const std::vector<can_signal_t>& signals,
-				float value, bool* send);
-
-
-		/* Public: Parse a signal from a CAN message, apply any required transforations
-		 *      to get a human readable value and public the result to the pipeline.
-		 *
-		* If the can_signal_t has a non-NULL 'decoder' field, the raw CAN signal value
-		* will be passed to the decoder before publishing.
-		*
-		* signal - The details of the signal to decode and forward.
-		* message   - The received CAN message that should contain this signal.
-		* signals - an array of all active signals.
-		*
-		* The decoder returns an openxc_DynamicField, which may contain a number,
-		* string or boolean.
-		*/
-		static openxc_DynamicField translateSignal(can_signal_t& signal, can_message_t& message,
-			const std::vector<can_signal_t>& signals);
-		
-		/* Public: Parse a signal from a CAN message and apply any required
-		* transforations to get a human readable value.
-		*
-		* If the can_signal_t has a non-NULL 'decoder' field, the raw CAN signal value
-		* will be passed to the decoder before returning.
-		*
-		* signal - The details of the signal to decode and forward.
-		* message   - The CAN message that contains the signal.
-		* signals - an array of all active signals.
-		* send - An output parameter that will be flipped to false if the value could
-		*      not be decoded.
-		*
-		* The decoder returns an openxc_DynamicField, which may contain a number,
-		* string or boolean. If 'send' is false, the return value is undefined.
-		*/
-		static openxc_DynamicField decodeSignal(can_signal_t& signal, const can_message_t& message,
-				const std::vector<can_signal_t>& signals, bool* send);
-
-		/* Public: Decode a transformed, human readable value from an raw CAN signal
-		* already parsed from a CAN message.
-		*
-		* This is the same as decodeSignal(const can_signal_t&, CanMessage*, const can_signal_t&, int,
-		* bool*) but you must parse the bitfield value of the signal from the CAN
-		* message yourself. This is useful if you need that raw value for something
-		* else.
-		*/
-		static openxc_DynamicField decodeSignal(can_signal_t& signal, float value,
+public:
+	static float parseSignalBitfield(can_signal_t& signal, const can_message_t& message);
+
+	static openxc_DynamicField stateDecoder(can_signal_t& signal, const std::vector<can_signal_t>& signals,
+			float value, bool* send);
+	static openxc_DynamicField booleanDecoder(can_signal_t& signal, const std::vector<can_signal_t>& signals,
+			float value, bool* send);
+	static openxc_DynamicField ignoreDecoder(can_signal_t& signal, const std::vector<can_signal_t>& signals,
+			float value, bool* send);
+	static openxc_DynamicField noopDecoder(can_signal_t& signal, const std::vector<can_signal_t>& signals,
+			float value, bool* send);
+
+	static openxc_DynamicField translateSignal(can_signal_t& signal, can_message_t& message,
+		const std::vector<can_signal_t>& signals);
+
+	static openxc_DynamicField decodeSignal(can_signal_t& signal, const can_message_t& message,
 			const std::vector<can_signal_t>& signals, bool* send);
+
+	static openxc_DynamicField decodeSignal(can_signal_t& signal, float value,
+		const std::vector<can_signal_t>& signals, bool* send);
 };
\ No newline at end of file
diff --git a/src/can/can-message-set.hpp b/src/can/can-message-set.hpp
index 89523201..94e2d8d5 100644
--- a/src/can/can-message-set.hpp
+++ b/src/can/can-message-set.hpp
@@ -33,15 +33,15 @@ private:
 	uint16_t can_signal_count_; /// < The number of CAN signals (across all messages) defined for this message set.
 	uint16_t can_command_count_; /// < The number of CanCommmands defined for this message set.
 	uint16_t obd2_signal_count_; /// < The number of obd2 signals defined for this message set.
-	
+
 public:
-	   can_message_set_t(
-		   uint8_t index,
-		   const std::string& name,
-		   uint8_t can_bus_count,
-		   short unsigned int can_message_count,
-		   short unsigned int can_signal_count,
-		   short unsigned int can_command_count,
-		   short unsigned int obd2_signal_count);
-	
+	can_message_set_t(
+			uint8_t index,
+			const std::string& name,
+			uint8_t can_bus_count,
+			short unsigned int can_message_count,
+			short unsigned int can_signal_count,
+			short unsigned int can_command_count,
+			short unsigned int obd2_signal_count);
+
 };
diff --git a/src/can/can-message.cpp b/src/can/can-message.cpp
index 36cce92f..cc4adb49 100644
--- a/src/can/can-message.cpp
+++ b/src/can/can-message.cpp
@@ -136,7 +136,10 @@ void can_message_t::set_format(const can_message_format_t new_format)
 *
 * This is the preferred way to initialize class members.
 *
-* @param[in] args - struct read from can bus device.
+* @param[in] frame - canfd_frame to convert coming from a read of CAN socket
+* @param[in] nbyte - 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_canfd_frame(const struct canfd_frame& frame, size_t nbytes)
 {