From 2eb313e5330dbfa1b6eab146b3698d8ffe054347 Mon Sep 17 00:00:00 2001 From: ydimitrov Date: Fri, 18 May 2018 21:12:14 +0100 Subject: Fixing typos made in comments This change set fixes the comments made by previous contributors v2: Fix line end v3: Making changes to comments as suggested by reviewers v4: Removing trailing spaces v5: Clearing small typo in low-can-cb.cpp on line 142 Change-Id: Ifbcfc3b2d131d1db0b25e472955b21e98cc09f45 Signed-off-by: ydimitrov --- examples/basic/application-generated.cpp | 2 +- examples/basic/handlers.cpp | 2 +- low-can-binding/binding/application.hpp | 10 +++---- low-can-binding/binding/low-can-cb.cpp | 18 ++++++------ low-can-binding/binding/low-can-socket.cpp | 34 +++++++++++------------ low-can-binding/binding/low-can-socket.hpp | 16 +++++------ low-can-binding/binding/low-can-subscription.hpp | 8 +++--- low-can-binding/can/can-bus-device.hpp | 8 +++--- low-can-binding/can/can-bus.cpp | 6 ++-- low-can-binding/can/can-bus.hpp | 10 +++---- low-can-binding/can/can-decoder.cpp | 6 ++-- low-can-binding/can/can-encoder.cpp | 4 +-- low-can-binding/can/can-message-set.cpp | 4 +-- low-can-binding/can/can-message-set.hpp | 4 +-- low-can-binding/can/can-message.cpp | 8 +++--- low-can-binding/can/can-signals.hpp | 4 +-- low-can-binding/diagnostic/diagnostic-manager.cpp | 4 +-- low-can-binding/diagnostic/diagnostic-manager.hpp | 4 +-- 18 files changed, 76 insertions(+), 76 deletions(-) diff --git a/examples/basic/application-generated.cpp b/examples/basic/application-generated.cpp index 1cdf67c3..18f7a7dc 100644 --- a/examples/basic/application-generated.cpp +++ b/examples/basic/application-generated.cpp @@ -22,7 +22,7 @@ void initializeMyStuff() { } void initializeOtherStuff() { } void myLooper() { - // this function will be called once each time through the main loop, after + // this function will be called once, each time through the main loop, after // all CAN message processing has been completed } diff --git a/examples/basic/handlers.cpp b/examples/basic/handlers.cpp index 4316f15f..f6e85d7f 100644 --- a/examples/basic/handlers.cpp +++ b/examples/basic/handlers.cpp @@ -17,6 +17,6 @@ void initializeMyStuff() { } void initializeOtherStuff() { } void myLooper() { - // this function will be called once each time through the main loop, after + // this function will be called once, each time through the main loop, after // all CAN message processing has been completed } diff --git a/low-can-binding/binding/application.hpp b/low-can-binding/binding/application.hpp index 93494872..92aca382 100644 --- a/low-can-binding/binding/application.hpp +++ b/low-can-binding/binding/application.hpp @@ -28,12 +28,12 @@ #include "../diagnostic/diagnostic-manager.hpp" /// -/// @brief Class representing a configuration attached to the binding. +/// @brief Class represents a configuration attached to the binding. /// -/// It regroups all needed objects instance from other class -/// that will be used along the binding life. It gets a global vision +/// It regroups all object instances from other classes +/// that will be used through the binding life. It receives a global vision /// on which signals are implemented for that binding. -/// Here, it is only the definition of the class with predefined accessors +/// Here, only the definition of the class is given with predefined accessors /// methods used in the binding. /// /// It will be the reference point to needed objects. @@ -41,7 +41,7 @@ class application_t { private: - can_bus_t can_bus_manager_; ///< instanciate the CAN bus manager. It's the one in charge of initialize the CAN bus devices. + can_bus_t can_bus_manager_; ///< instanciate the CAN bus manager. It's responsible of initializing the CAN bus devices. diagnostic_manager_t diagnostic_manager_; ///< Diagnostic manager use to manage diagnostic message communication. uint8_t active_message_set_ = 0; ///< Which is the active message set ? Default to 0. diff --git a/low-can-binding/binding/low-can-cb.cpp b/low-can-binding/binding/low-can-cb.cpp index bff5c935..c81cb9a2 100644 --- a/low-can-binding/binding/low-can-cb.cpp +++ b/low-can-binding/binding/low-can-cb.cpp @@ -138,8 +138,8 @@ static int create_event_handle(std::shared_ptr& can_subs return 0; } -/// @brief Will determine if it is needed or not to create the event handle and checks it to be sure that -/// we got a valid afb_event to get subscribe or unsubscribe. Then launch the subscription or unsubscription +/// @brief This will determine if an event handle needs to be created and checks if +/// we got a valid afb_event to get subscribe or unsubscribe. After that launch the subscription or unsubscription /// against the application framework using that event handle. static int subscribe_unsubscribe_signal(struct afb_req request, bool subscribe, @@ -166,8 +166,8 @@ static int subscribe_unsubscribe_signal(struct afb_req request, ret = create_event_handle(can_subscription, s); } - // Check whether or not the event handler has been correctly created and - // make the subscription/unsubscription operation is so. + // Checks if the event handler is correctly created, if it is, it + // performs the subscription or unsubscription operations. if (ret < 0) return ret; return make_subscription_unsubscription(request, can_subscription, s, subscribe); @@ -205,8 +205,8 @@ static int subscribe_unsubscribe_diagnostic_messages(struct afb_req request, can_subscription = it != s.end() ? it->second : std::make_shared(low_can_subscription_t(event_filter)); - // If the requested diagnostic message isn't supported by the car then unsubcribe it - // no matter what we want, worse case will be a fail unsubscription but at least we don't + // If the requested diagnostic message is not supported by the car then unsubcribe it + // no matter what we want, worst case will be a failed unsubscription but at least we won't // poll a PID for nothing. if(sig->get_supported() && subscribe) { @@ -281,8 +281,8 @@ static int subscribe_unsubscribe_can_signals(struct afb_req request, /// /// @brief subscribe to all signals in the vector signals /// -/// @param[in] afb_req request : contain original request use to subscribe or unsubscribe -/// @param[in] subscribe boolean value used to chose between a subscription operation or an unsubscription +/// @param[in] afb_req request : contains original request use to subscribe or unsubscribe +/// @param[in] subscribe boolean value, which chooses between a subscription operation or an unsubscription /// @param[in] signals - struct containing vectors with can_signal_t and diagnostic_messages to subscribe /// /// @return Number of correctly subscribed signal @@ -666,7 +666,7 @@ int initv2() if(application_t::instance().get_diagnostic_manager().initialize()) ret = 0; - // Add a recurring dignostic message request to get engine speed continuously + // Add a recurring dignostic message request to get engine speed at all times. openxc_DynamicField search_key = build_DynamicField("diagnostic_messages.engine.speed"); struct utils::signals_found sf = utils::signals_manager_t::instance().find_signals(search_key); diff --git a/low-can-binding/binding/low-can-socket.cpp b/low-can-binding/binding/low-can-socket.cpp index 8a8efbf7..0aebfa3c 100644 --- a/low-can-binding/binding/low-can-socket.cpp +++ b/low-can-binding/binding/low-can-socket.cpp @@ -163,10 +163,10 @@ void low_can_socket_t::set_max(float max) { event_filter_.max = max; } -/// @brief Based upon which object is subscribed CAN signal or diagnostic message -/// this will open the socket with the required CAN bus device name. +/// @brief Based upon which object is a subscribed CAN signal or diagnostic message +/// it will open the socket with the required CAN bus device name. /// -/// @return INVALID_SOCKET on failure else positive integer +/// @return INVALID_SOCKET on failure, else positive integer int low_can_socket_t::open_socket(const std::string& bus_name) { int ret = 0; @@ -183,9 +183,9 @@ int low_can_socket_t::open_socket(const std::string& bus_name) return ret; } -/// @brief Build a BCM message head but don't set can_frame. +/// @brief Builds a BCM message head but doesn't set can_frame. /// -/// @return a simple_bcm_msg with the msg_head parts set and can_frame +/// @returns a simple_bcm_msg with the msg_head parts set and can_frame /// zeroed. struct utils::simple_bcm_msg low_can_socket_t::make_bcm_head(uint32_t opcode, uint32_t can_id, uint32_t flags, const struct timeval& timeout, const struct timeval& frequency_thinning) const { @@ -203,8 +203,8 @@ struct utils::simple_bcm_msg low_can_socket_t::make_bcm_head(uint32_t opcode, ui return bcm_msg; } -/// @brief Take an existing simple_bcm_msg struct and add a can_frame to it. -/// Only possible for now to add 1 uniq can_frame, it isn't possible to build +/// @brief Take an existing simple_bcm_msg struct and add a can_frame. +/// Currently only 1 uniq can_frame can be added, it's not possible to build /// a multiplexed message with several can_frame. void low_can_socket_t::add_bcm_frame(const struct can_frame& cf, struct utils::simple_bcm_msg& bcm_msg) const { @@ -219,7 +219,7 @@ void low_can_socket_t::add_bcm_frame(const struct can_frame& cf, struct utils::s } } -/// @brief Create a RX_SETUP receive job used by the BCM socket for a CAN signal +/// @brief Create a RX_SETUP receive job to be used by the BCM socket for a CAN signal /// subscription /// /// @return 0 if ok else -1 @@ -249,7 +249,7 @@ int low_can_socket_t::create_rx_filter(std::shared_ptr sig) return create_rx_filter(bcm_msg); } -/// @brief Create a RX_SETUP receive job used by the BCM socket for a +/// @brief Create a RX_SETUP receive job to be used by the BCM socket for a /// diagnostic message subscription. /// /// @return 0 if ok else -1 @@ -266,7 +266,7 @@ int low_can_socket_t::create_rx_filter(std::shared_ptr sig } /// @brief Create a RX_SETUP receive job used by the BCM socket directly from -/// a simple_bcm_msg. You will not use this method directly but rather use the +/// a simple_bcm_msg. The method should not be used directly but rather through the /// two previous method with can_signal_t or diagnostic_message_t object. /// /// If the CAN arbitration ID is the OBD2 functional broadcast id the subscribed @@ -275,11 +275,11 @@ int low_can_socket_t::create_rx_filter(std::shared_ptr sig /// @return 0 if ok else -1 int low_can_socket_t::create_rx_filter(utils::simple_bcm_msg& bcm_msg) { - // Make sure that socket has been opened. + // Make sure that socket is opened. if(open_socket() < 0) {return -1;} - // If it isn't an OBD2 CAN ID then just add a simple RX_SETUP job + // If it's not an OBD2 CAN ID then just add a simple RX_SETUP job // else monitor all standard 8 CAN OBD2 ID response. if(bcm_msg.msg_head.can_id != OBD2_FUNCTIONAL_BROADCAST_ID) { @@ -302,10 +302,10 @@ int low_can_socket_t::create_rx_filter(utils::simple_bcm_msg& bcm_msg) return 0; } -/// @brief Create a TX_SEND job used by the BCM socket to -/// simply send message +/// @brief Creates a TX_SEND job that is used by the BCM socket to +/// send a message /// -/// @return 0 if ok else -1 +/// @return 0 if ok, else -1 int low_can_socket_t::tx_send(const struct can_frame& cf, std::shared_ptr sig) { can_signal_ = sig; @@ -323,8 +323,8 @@ int low_can_socket_t::tx_send(const struct can_frame& cf, std::shared_ptr can_signal_; ///< can_signal_ - the CAN signal subscribed - std::vector > diagnostic_message_; ///< diagnostic_message_ - diagnostic messages meant to received OBD2 responses. - /// normal diagnostic request and response not tested for now. + std::vector > diagnostic_message_; ///< diagnostic_message_ - diagnostic messages meant to receive OBD2 responses. + /// normal diagnostic request and response are not tested for now. utils::socketcan_bcm_t socket_; ///< socket_ - socket_ that receives CAN messages. diff --git a/low-can-binding/binding/low-can-subscription.hpp b/low-can-binding/binding/low-can-subscription.hpp index 239154a2..2e656b9a 100644 --- a/low-can-binding/binding/low-can-subscription.hpp +++ b/low-can-binding/binding/low-can-subscription.hpp @@ -26,10 +26,10 @@ #include "../diagnostic/diagnostic-message.hpp" #include "../utils/socketcan-bcm.hpp" -/// @brief A subscription object used has a context that handle all needed values to describe a subscription -/// to the low-can binding. It can holds a CAN signal or diagnostic message. Diagnostic message for OBD2 is a kind -/// of special because there is only 1 listener to retrieve OBD2 requests. So it's needed that all diagnostic messages -/// subscriptions is to be in 1 object. +/// @brief The subscription class has a context that can handle all needed values to describe a subscription +/// to the low-can binding. It can hold a CAN signal or a diagnostic message. A diagnostic message for OBD2 is +/// special because there is only 1 listener to retrieve OBD2 requests. It is required that all diagnostic message +/// subscriptions are in 1 object. class low_can_subscription_t : public low_can_socket_t { private: diff --git a/low-can-binding/can/can-bus-device.hpp b/low-can-binding/can/can-bus-device.hpp index af705515..c53e5f23 100644 --- a/low-can-binding/can/can-bus-device.hpp +++ b/low-can-binding/can/can-bus-device.hpp @@ -45,12 +45,12 @@ private: std::string name; std::string device_name; float max_message_frequency; // >& s); void can_decode_message(); - std::thread th_decoding_; ///< thread that'll handle decoding a can frame + std::thread th_decoding_; ///< thread that will handle decoding a can frame bool is_decoding_ = false; ///< boolean member controling thread while loop void can_event_push(); - std::thread th_pushing_; ///< thread that'll handle pushing decoded can frame to subscribers + std::thread th_pushing_; ///< thread that will handle pushing decoded can frame to subscribers bool is_pushing_ = false; ///< boolean member controling thread while loop std::condition_variable new_can_message_cv_; ///< condition_variable use to wait until there is a new CAN message to read std::mutex can_message_mutex_; ///< mutex protecting the can_message_q_ queue. - std::queue can_message_q_; ///< queue that'll store can_message_t to decoded + std::queue can_message_q_; ///< queue that will store can_message_t to be decoded 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 > vehicle_message_q_; ///< queue that'll store openxc_VehicleMessage to pushed + std::queue > vehicle_message_q_; ///< queue that will store openxc_VehicleMessage to be pushed std::vector > can_devices_mapping_; ///< can_devices_mapping_ - holds a mapping between logical CAN devices names and linux CAN devices names. public: diff --git a/low-can-binding/can/can-decoder.cpp b/low-can-binding/can/can-decoder.cpp index 0c81d7a6..763bfcb0 100644 --- a/low-can-binding/can/can-decoder.cpp +++ b/low-can-binding/can/can-decoder.cpp @@ -22,10 +22,10 @@ #include "can-message-definition.hpp" #include "../binding/low-can-hat.hpp" -/// @brief Parse the signal's bitfield from the given data and return the raw +/// @brief Parses the signal's bitfield from the given data and returns the raw /// value. /// -/// @param[in] signal - The signal to parse from the data. +/// @param[in] signal - The signal to be parsed 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 @@ -38,7 +38,7 @@ float decoder_t::parse_signal_bitfield(can_signal_t& signal, const can_message_t signal.get_offset()); } -/// @brief Wrap a raw CAN signal value in a DynamicField without modification. +/// @brief Wraps a raw CAN signal value in a DynamicField without modification. /// /// This is an implementation of the Signal type signature, and can be /// used directly in the can_signal_t.decoder field. diff --git a/low-can-binding/can/can-encoder.cpp b/low-can-binding/can/can-encoder.cpp index 5dc632b3..d90e08da 100644 --- a/low-can-binding/can/can-encoder.cpp +++ b/low-can-binding/can/can-encoder.cpp @@ -21,10 +21,10 @@ #include "../utils/openxc-utils.hpp" #include "can-message-definition.hpp" -/// @brief Write a value into a CAN signal in the destination buffer. +/// @brief Write a value in a CAN signal in the destination buffer. /// /// @param[in] signal - The CAN signal to write, including the bit position and bit size. -/// @param[in] value - The encoded integer value to write into the CAN signal. +/// @param[in] value - The encoded integer value to write in the CAN signal. /// @param[out] data - The destination buffer. /// @param[in] length - The length of the destination buffer. /// diff --git a/low-can-binding/can/can-message-set.cpp b/low-can-binding/can/can-message-set.cpp index c31dec62..a5cf8819 100644 --- a/low-can-binding/can/can-message-set.cpp +++ b/low-can-binding/can/can-message-set.cpp @@ -31,7 +31,7 @@ can_message_set_t::can_message_set_t( , diagnostic_messages_{diagnostic_messages} {} -/// @brief Return vector holding all message definition handled by this message set. +/// @brief Returns a vector holding all message definitions which are handled by this message set. std::vector >& can_message_set_t::get_can_message_definition() { return can_messages_definition_; @@ -52,7 +52,7 @@ std::vector > can_message_set_t::get_all_can_signa return can_signals; } -/// @brief Return vector holding all diagnostic messages definitions handled by this message set. +/// @brief Returns a vector holding all diagnostic message definitions which are handled by this message set. std::vector >& can_message_set_t::get_diagnostic_messages() { return diagnostic_messages_; diff --git a/low-can-binding/can/can-message-set.hpp b/low-can-binding/can/can-message-set.hpp index bf53c8c5..59c27b1a 100644 --- a/low-can-binding/can/can-message-set.hpp +++ b/low-can-binding/can/can-message-set.hpp @@ -32,9 +32,9 @@ class diagnostic_message_t; class can_message_set_t { private: - uint8_t index_; /// < A numerical ID for the message set, ideally the index in an array for fast lookup + uint8_t index_; /// < A numerical ID for the message set, ideally the index is in an array for fast lookup const std::string name_; /// < The name of the message set. - std::vector > can_messages_definition_; ///< Vector holding all message definition handled by this message set. + std::vector > can_messages_definition_; ///< Vector holding all message definitions handled by the message set. std::vector > diagnostic_messages_; ///< Vector holding all diagnostics messages from JSON signals description file. First vector map to message set public: diff --git a/low-can-binding/can/can-message.cpp b/low-can-binding/can/can-message.cpp index 8221e303..1b27d0f6 100644 --- a/low-can-binding/can/can-message.cpp +++ b/low-can-binding/can/can-message.cpp @@ -24,7 +24,7 @@ /// /// @brief Class constructor /// -/// Constructor about can_message_t class. +/// can_message_t class constructor. /// can_message_t::can_message_t() : maxdlen_{0}, @@ -167,7 +167,7 @@ bool can_message_t::is_correct_to_send() /// @brief Set format_ member value. /// -/// Preferred way to initialize these members by using +/// Preferred way to initialize these members is to use /// convert_from_canfd_frame method. /// /// @param[in] new_format - class member @@ -346,7 +346,7 @@ 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 +/// @brief Take all initialized class members and build a /// canfd_frame struct that can be use to send a CAN message over /// the bus. /// @@ -367,7 +367,7 @@ struct canfd_frame can_message_t::convert_to_canfd_frame() return frame; } -/// @brief Take all initialized class's members and build an +/// @brief Take all initialized class members and build a /// can_frame struct that can be use to send a CAN message over /// the bus. /// diff --git a/low-can-binding/can/can-signals.hpp b/low-can-binding/can/can-signals.hpp index ea8c077b..31e0c6a6 100644 --- a/low-can-binding/can/can-signals.hpp +++ b/low-can-binding/can/can-signals.hpp @@ -43,8 +43,8 @@ class can_signal_t; /// @param[in] signalCount - The length of the signals array. /// @param[in] value - The CAN signal parsed from the message as a raw floating point /// value. -/// @param[out] send - An output parameter. If the decoding failed or the CAN signal should -/// not send for some other reason, this should be flipped to false. +/// @param[out] send - An output parameter. If decoding fails or CAN signal is +/// not sending, this should be flipped to false. /// /// @return a decoded value in an openxc_DynamicField struct. /// diff --git a/low-can-binding/diagnostic/diagnostic-manager.cpp b/low-can-binding/diagnostic/diagnostic-manager.cpp index 2f22b14d..bc335dfc 100644 --- a/low-can-binding/diagnostic/diagnostic-manager.cpp +++ b/low-can-binding/diagnostic/diagnostic-manager.cpp @@ -49,8 +49,8 @@ diagnostic_manager_t::~diagnostic_manager_t() } } -/// @brief Diagnostic manager isn't initialized at launch but after -/// CAN bus devices initialization. For the moment, it is only possible +/// @brief Diagnostic manager is not initialized at launch but after +/// the initialization of CAN bus devices. For the moment, it is only possible /// to have 1 diagnostic bus which are the first bus declared in the JSON /// description file. Configuration instance will return it. /// diff --git a/low-can-binding/diagnostic/diagnostic-manager.hpp b/low-can-binding/diagnostic/diagnostic-manager.hpp index 75d08e20..896a2b60 100644 --- a/low-can-binding/diagnostic/diagnostic-manager.hpp +++ b/low-can-binding/diagnostic/diagnostic-manager.hpp @@ -27,7 +27,7 @@ #include "../can/can-bus.hpp" #include "active-diagnostic-request.hpp" -/// Each CAN bus needs its own set of shim functions, so this should +/// Each CAN bus requires its own set of shim functions, so this should /// match the maximum CAN controller count. /// #define DIAGNOSTIC_RESPONSE_ARBITRATION_ID_OFFSET 0x8 @@ -35,7 +35,7 @@ class active_diagnostic_request_t; /// -/// @brief The core structure for running the diagnostics module by the binding. +/// @brief The core structure for running the diagnostics module of the binding. /// /// This stores details about the active requests and shims required to connect /// the diagnostics library to the CAN device. -- cgit 1.2.3-korg