[CI/Meta]: Add documentation validation checking

.github/workflows/linting.yml

@@ -34,3 +34,13 @@ jobs:
         run: find . -name CMakeLists.txt | xargs cmake-format -i
       - name: Check cmake-format
         run: git diff --patch-with-stat --exit-code
+  doxygen:
+    name: verify doxygen
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Generate Doxygen Documentation
+        uses: mattnotmitt/[email protected]
+        with:
+          doxyfile-path: 'doxyfile'

hardware_integration/include/isobus/hardware_integration/can_hardware_interface.hpp

@@ -138,6 +138,7 @@ namespace isobus
 
 		/// @brief Attempts to write a frame using the driver assigned to a frame's channel
 		/// @param[in] frame The frame to try and write to the bus
+		/// @returns `true` if the frame was sent from the buffer, otherwise `false`
 		static bool transmit_can_frame_from_buffer(const isobus::CANMessageFrame &frame);
 
 		/// @brief The periodic update thread executes this function

hardware_integration/include/isobus/hardware_integration/can_hardware_interface_single_thread.hpp

@@ -116,6 +116,7 @@ namespace isobus
 
 		/// @brief Attempts to write a frame using the driver assigned to a frame's channel
 		/// @param[in] frame The frame to try and write to the bus
+		/// @returns `true` if the frame was transmitted, otherwise `false`
 		static bool transmit_can_frame_from_buffer(const isobus::CANMessageFrame &frame);
 
 		static isobus::EventDispatcher<const isobus::CANMessageFrame &> frameReceivedEventDispatcher; ///< The event dispatcher for when a CAN message frame is received from hardware event

hardware_integration/include/isobus/hardware_integration/can_hardware_plugin.hpp

@@ -27,10 +27,11 @@ namespace isobus
 		/// @returns `true` if the driver is good/connected, `false` if the driver is not usable
 		virtual bool get_is_valid() const = 0;
 
-		/// @brief Disconnects the driver from the hardware
+		/// @brief Disconnects the driver from the hardware.
 		virtual void close() = 0;
 
-		/// @brief Connects the driver to the hardware
+		/// @brief Connects the driver to the hardware. This will be called to initialize the driver
+		/// and connect it to the hardware.
 		virtual void open() = 0;
 
 		/// @brief Reads one frame from the bus synchronously

hardware_integration/include/isobus/hardware_integration/flex_can_t4_plugin.hpp

@@ -56,8 +56,8 @@ namespace isobus
 		static FlexCAN_T4<CAN1, RX_SIZE_256, TX_SIZE_512> can0;
 		static FlexCAN_T4<CAN2, RX_SIZE_256, TX_SIZE_512> can1;
 #endif
-		std::uint8_t selectedChannel;
-		bool isOpen = false;
+		std::uint8_t selectedChannel; ///< The channel that this plugin is assigned to
+		bool isOpen = false; ///< Tracks if the connection is open/connected
 	};
 }
 #endif // FLEX_CAN_T4_PLUGIN_HPP

hardware_integration/include/isobus/hardware_integration/mcp2515_can_interface.hpp

@@ -51,6 +51,7 @@ namespace isobus
 		void open() override;
 
 		/// @brief Resets the MCP2515
+		/// @returns `true` if the reset was successful, otherwise `false`
 		bool reset();
 
 		/// @brief Returns a frame from the hardware (synchronous), or `false` if no frame can be read.

hardware_integration/src/can_hardware_interface.cpp

@@ -43,7 +43,7 @@ namespace isobus
 		return CANHardwareInterface::transmit_can_frame(frame);
 	}
 
-	bool CANHardwareInterface::set_number_of_can_channels(uint8_t value)
+	bool CANHardwareInterface::set_number_of_can_channels(std::uint8_t value)
 	{
 		std::lock_guard<std::mutex> lock(hardwareChannelsMutex);
 

hardware_integration/src/can_hardware_interface_single_thread.cpp

@@ -29,7 +29,7 @@ namespace isobus
 		return CANHardwareInterface::transmit_can_frame(frame);
 	}
 
-	bool CANHardwareInterface::set_number_of_can_channels(uint8_t value)
+	bool CANHardwareInterface::set_number_of_can_channels(std::uint8_t value)
 	{
 		if (started)
 		{

isobus/include/isobus/isobus/can_NAME_filter.hpp

@@ -39,6 +39,7 @@ namespace isobus
 		std::uint32_t get_value() const;
 
 		/// @brief Returns true if a NAME matches this filter class's components
+		/// @param[in] nameToCompare A NAME to compare against this filter
 		/// @returns true if a NAME matches this filter class's components
 		bool check_name_matches_filter(const NAME &nameToCompare) const;
 

isobus/include/isobus/isobus/can_address_claim_state_machine.hpp

@@ -89,13 +89,16 @@ namespace isobus
 		static void process_rx_message(const CANMessage &message, void *parentPointer);
 
 		/// @brief Sets the current state machine state
+		/// @param[in] value The state to set the state machine to
 		void set_current_state(State value);
 
 		/// @brief Sends the PGN request for the address claim PGN
+		/// @returns true if the message was sent, otherwise false
 		bool send_request_to_claim() const;
 
 		/// @brief Sends the address claim message
 		/// @param[in] address The address to claim
+		/// @returns true if the message was sent, otherwise false
 		bool send_address_claim(std::uint8_t address);
 
 		NAME m_isoname; ///< The ISO NAME to claim as

isobus/include/isobus/isobus/can_callbacks.hpp

@@ -101,6 +101,7 @@ namespace isobus
 		CANLibCallback get_callback() const;
 
 		/// @brief Returns the parent pointer for this data object
+		/// @returns The parent pointer for this data object
 		void *get_parent() const;
 
 		/// @brief Returns the ICF being used as a filter for this callback

isobus/include/isobus/isobus/can_control_function.hpp

@@ -43,6 +43,7 @@ namespace isobus
 		/// @param[in] NAMEValue The NAME of the control function
 		/// @param[in] addressValue The current address of the control function
 		/// @param[in] CANPort The CAN channel index that the control function communicates on
+		/// @returns A shared pointer to a ControlFunction object created with the parameters passed in
 		static std::shared_ptr<ControlFunction> create(NAME NAMEValue, std::uint8_t addressValue, std::uint8_t CANPort);
 
 		/// @brief Destroys this control function, by removing it from the network manager
@@ -82,7 +83,7 @@ namespace isobus
 		/// @param[in] type The 'Type' of control function to create
 		ControlFunction(NAME NAMEValue, std::uint8_t addressValue, std::uint8_t CANPort, Type type = Type::External);
 
-		friend class CANNetworkManager;
+		friend class CANNetworkManager; ///< The network manager needs access to the control function's internals
 #if !defined CAN_STACK_DISABLE_THREADS && !defined ARDUINO
 		static std::mutex controlFunctionProcessingMutex; ///< Protects the control function tables
 #endif

isobus/include/isobus/isobus/can_extended_transport_protocol.hpp

@@ -75,10 +75,12 @@ namespace isobus
 			enum class Direction
 			{
 				Transmit, ///< We are transmitting a message
-				Receive ///< We are receving a message
+				Receive ///< We are receiving a message
 			};
 
-			/// @brief A useful way to compare sesson objects to each other for equality
+			/// @brief A useful way to compare session objects to each other for equality
+			/// @param[in] obj The object to compare against
+			/// @returns true if the objects are equal, false if not
 			bool operator==(const ExtendedTransportProtocolSession &obj);
 
 			/// @brief Get the total number of bytes that will be sent or received in this session
@@ -175,6 +177,7 @@ namespace isobus
 		/// @param[in] reason The reason we're aborting the session
 		/// @param[in] source The source control function from which we'll send the abort
 		/// @param[in] destination The destination control function to which we'll send the abort
+		/// @returns true if the abort was sent OK, false if not sent
 		bool abort_session(std::uint32_t parameterGroupNumber, ConnectionAbortReason reason, std::shared_ptr<InternalControlFunction> source, std::shared_ptr<ControlFunction> destination);
 
 		/// @brief Gracefully closes a session to prepare for a new session
@@ -186,13 +189,15 @@ namespace isobus
 		/// @param[in] source The source control function for the session
 		/// @param[in] destination The destination control function for the session
 		/// @param[out] session The found session, or nullptr if no session matched the supplied parameters
+		/// @returns true if a matching session was found, false if not
 		bool get_session(ExtendedTransportProtocolSession *&session, std::shared_ptr<ControlFunction> source, std::shared_ptr<ControlFunction> destination) const;
 
 		/// @brief Gets an ETP session from the passed in source and destination and PGN combination
 		/// @param[in] source The source control function for the session
 		/// @param[in] destination The destination control function for the session
 		/// @param[in] parameterGroupNumber The PGN of the session
 		/// @param[out] session The found session, or nullptr if no session matched the supplied parameters
+		/// @returns true if a matching session was found, false if not
 		bool get_session(ExtendedTransportProtocolSession *&session, std::shared_ptr<ControlFunction> source, std::shared_ptr<ControlFunction> destination, std::uint32_t parameterGroupNumber) const;
 
 		/// @brief Processes end of session callbacks

isobus/include/isobus/isobus/can_hardware_abstraction.hpp

@@ -18,6 +18,7 @@ namespace isobus
 {
 	/// @brief The sending abstraction layer between the hardware and the stack
 	/// @param[in] frame The frame to transmit from the hardware
+	/// @returns true if the frame was successfully sent, false otherwise
 	bool send_can_message_frame_to_hardware(const CANMessageFrame &frame);
 
 	/// @brief The receiving abstraction layer between the hardware and the stack

isobus/include/isobus/isobus/can_identifier.hpp

@@ -68,6 +68,7 @@ namespace isobus
 
 		/// @brief Assignment operator for a CAN identifier
 		/// @param[in] obj rhs of the operator
+		/// @returns The lhs of the operator, now assigned the rhs value
 		CANIdentifier &operator=(const CANIdentifier &obj);
 
 		/// @brief Returns the raw encoded ID of the CAN identifier

isobus/include/isobus/isobus/can_internal_control_function.hpp

@@ -38,6 +38,7 @@ namespace isobus
 		/// @param[in] desiredName The NAME for this control function to claim as
 		/// @param[in] preferredAddress The preferred NAME for this control function
 		/// @param[in] CANPort The CAN channel index for this control function to use
+		/// @returns A shared pointer to an InternalControlFunction object created with the parameters passed in
 		static std::shared_ptr<InternalControlFunction> create(NAME desiredName, std::uint8_t preferredAddress, std::uint8_t CANPort);
 
 		/// @brief Destroys this control function, by removing it from the network manager
@@ -57,6 +58,7 @@ namespace isobus
 
 		/// @brief Used by the network manager to tell the ICF that the address claim state machine needs to process
 		/// a J1939 command to move address.
+		/// @param[in] commandedAddress The address that the ICF has been commanded to move to
 		void process_commanded_address(std::uint8_t commandedAddress, CANLibBadge<CANNetworkManager>);
 
 		/// @brief Updates the internal control function together with it's associated address claim state machine

isobus/include/isobus/isobus/can_network_manager.hpp

@@ -89,6 +89,7 @@ namespace isobus
 		void remove_any_control_function_parameter_group_number_callback(std::uint32_t parameterGroupNumber, CANLibCallback callback, void *parent);
 
 		/// @brief Returns an internal control function if the passed-in control function is an internal type
+		/// @param[in] controlFunction The control function to get the internal control function from
 		/// @returns An internal control function casted from the passed in control function
 		std::shared_ptr<InternalControlFunction> get_internal_control_function(std::shared_ptr<ControlFunction> controlFunction);
 
@@ -106,6 +107,15 @@ namespace isobus
 		/// If you don't specify a destination (or use nullptr) you message will be sent as a broadcast
 		/// if it is valid to do so.
 		/// You can also get a callback on success or failure of the transmit.
+		/// @param[in] parameterGroupNumber The PGN to use when sending the message
+		/// @param[in] dataBuffer A pointer to the data buffer to send from
+		/// @param[in] dataLength The size of the message to send
+		/// @param[in] sourceControlFunction The control function that is sending the message
+		/// @param[in] destinationControlFunction The control function that the message is destined for or nullptr if broadcast
+		/// @param[in] priority The CAN priority of the message being sent
+		/// @param[in] txCompleteCallback A callback to be called when the message is sent or fails to send
+		/// @param[in] parentPointer A generic context variable that helps identify what object the callback is destined for
+		/// @param[in] frameChunkCallback A callback which can be supplied to have the tack call you back to get chunks of the message as they are sent
 		/// @returns `true` if the message was sent, otherwise `false`
 		bool send_can_message(std::uint32_t parameterGroupNumber,
 		                      const std::uint8_t *dataBuffer,
@@ -189,7 +199,7 @@ namespace isobus
 		friend class DiagnosticProtocol; ///< Allows the diagnostic protocol to access the protected functions on the network manager
 		friend class ParameterGroupNumberRequestProtocol; ///< Allows the PGN request protocol to access the network manager protected functions
 		friend class FastPacketProtocol; ///< Allows the FP protocol to access the network manager protected functions
-		friend class CANLibProtocol;
+		friend class CANLibProtocol; ///< Allows the CANLib protocol base class functions to access the network manager protected functions
 
 		/// @brief Adds a PGN callback for a protocol class
 		/// @param[in] parameterGroupNumber The PGN to register for
@@ -374,7 +384,7 @@ namespace isobus
 		std::list<ControlFunctionStateCallback> controlFunctionStateCallbacks; ///< List of all control function state callbacks
 		std::vector<ParameterGroupNumberCallbackData> globalParameterGroupNumberCallbacks; ///< A list of all global PGN callbacks
 		std::vector<ParameterGroupNumberCallbackData> anyControlFunctionParameterGroupNumberCallbacks; ///< A list of all global PGN callbacks
-		EventDispatcher<std::shared_ptr<InternalControlFunction>> addressViolationEventDispatcher; // An event dispatcher for notifying consumers about address violations
+		EventDispatcher<std::shared_ptr<InternalControlFunction>> addressViolationEventDispatcher; ///< An event dispatcher for notifying consumers about address violations
 #if !defined CAN_STACK_DISABLE_THREADS && !defined ARDUINO
 		std::mutex receiveMessageMutex; ///< A mutex for receive messages thread safety
 		std::mutex protocolPGNCallbacksMutex; ///< A mutex for PGN callback thread safety

isobus/include/isobus/isobus/can_partnered_control_function.hpp

@@ -41,6 +41,7 @@ namespace isobus
 		/// @brief The factory function to construct a partnered control function
 		/// @param[in] CANPort The CAN channel associated with this control function definition
 		/// @param[in] NAMEFilters A list of filters that describe the identity of the CF based on NAME components
+		/// @returns A shared pointer to a PartneredControlFunction object created with the parameters passed in
 		static std::shared_ptr<PartneredControlFunction> create(std::uint8_t CANPort, const std::vector<NAMEFilter> NAMEFilters);
 
 		/// @brief the constructor for a PartneredControlFunction, which is called by the factory function

isobus/include/isobus/isobus/can_transport_protocol.hpp

@@ -62,6 +62,8 @@ namespace isobus
 			};
 
 			/// @brief A useful way to compare sesson objects to each other for equality
+			/// @param[in] obj The object to compare to
+			/// @returns true if the objects are equal, false if not
 			bool operator==(const TransportProtocolSession &obj);
 
 			/// @brief Get the total number of bytes that will be sent or received in this session
@@ -216,13 +218,15 @@ namespace isobus
 		/// @param[in] source The source control function for the session
 		/// @param[in] destination The destination control function for the session
 		/// @param[out] session The found session, or nullptr if no session matched the supplied parameters
+		/// @returns true if a matching session was found, false if not
 		bool get_session(TransportProtocolSession *&session, std::shared_ptr<ControlFunction> source, std::shared_ptr<ControlFunction> destination);
 
 		/// @brief Gets a TP session from the passed in source and destination and PGN combination
 		/// @param[in] source The source control function for the session
 		/// @param[in] destination The destination control function for the session
 		/// @param[in] parameterGroupNumber The PGN of the session
 		/// @param[out] session The found session, or nullptr if no session matched the supplied parameters
+		/// @returns true if a matching session was found, false if not
 		bool get_session(TransportProtocolSession *&session, std::shared_ptr<ControlFunction> source, std::shared_ptr<ControlFunction> destination, std::uint32_t parameterGroupNumber);
 
 		/// @brief Updates the state machine of a Tp session

isobus/include/isobus/isobus/isobus_device_descriptor_object_pool.hpp

@@ -136,10 +136,12 @@ namespace isobus
 		bool generate_binary_object_pool(std::vector<std::uint8_t> &resultantPool);
 
 		/// @brief Gets an object from the DDOP that corresponds to a certain object ID
+		/// @param[in] objectID The ID of the object to get
 		/// @returns Pointer to the object matching the provided ID, or nullptr if no match was found
 		std::shared_ptr<task_controller_object::Object> get_object_by_id(std::uint16_t objectID);
 
 		/// @brief Gets an object from the DDOP by index based on object creation
+		/// @param[in] index The index of the object to get
 		/// @returns Pointer to the object matching the index, or nullptr if no match was found
 		std::shared_ptr<task_controller_object::Object> get_object_by_index(std::uint16_t index);
 

isobus/include/isobus/isobus/isobus_diagnostic_protocol.hpp

@@ -204,7 +204,7 @@ namespace isobus
 			FailureModeIdentifier get_failure_mode_identifier() const;
 
 		private:
-			friend class DiagnosticProtocol;
+			friend class DiagnosticProtocol; ///< Allows the protocol to set the occurrence count
 			std::uint32_t suspectParameterNumber = 0xFFFFFFFF; ///< This 19-bit number is used to identify the item for which diagnostics are being reported
 			FailureModeIdentifier failureModeIdentifier = FailureModeIdentifier::ConditionExists; ///< The FMI defines the type of failure detected in the sub-system identified by an SPN
 			LampStatus lampState = LampStatus::None; ///< The J1939 lamp state for this DTC
@@ -221,6 +221,7 @@ namespace isobus
 		~DiagnosticProtocol();
 
 		/// @brief The protocol's initializer function
+		/// @returns true if the protocol was initialized, false if it was already initialized
 		bool initialize();
 
 		/// @brief Returns if the protocol has been initialized

isobus/include/isobus/isobus/isobus_functionalities.hpp

@@ -455,6 +455,7 @@ namespace isobus
 		/// @param[out] acknowledge Tells the PGN request protocol to ACK ack the request
 		/// @param[out] acknowledgeType Tells the PGN request protocol what kind of ACK to use
 		/// @param[in] parentPointer A generic context variable, usually the "this" pointer of the registrant for callbacks
+		/// @returns true if the PGN was handled, otherwise false
 		static bool pgn_request_handler(std::uint32_t parameterGroupNumber,
 		                                std::shared_ptr<ControlFunction> requestingControlFunction,
 		                                bool &acknowledge,

isobus/include/isobus/isobus/isobus_guidance_interface.hpp

@@ -262,6 +262,7 @@ namespace isobus
 			/// @brief Sets the exit code for the guidance system
 			/// @details This parameter is used to indicate why the guidance system cannot currently accept
 			/// remote commands or has most recently stopped accepting remote commands.
+			/// @param[in] exitCode The exit code for the guidance system to report
 			/// @returns The exit code for the guidance system
 			bool set_guidance_system_command_exit_reason_code(std::uint8_t exitCode);
 
@@ -334,13 +335,15 @@ namespace isobus
 		/// @param[in] index An index of senders of the agricultural guidance machine info message
 		/// @note Only one device on the bus will send this normally, but we provide a generic way to get
 		/// an arbitrary number of these commands. So generally using only index 0 will be acceptable.
+		/// @returns The content of the agricultural guidance machine info message
 		std::shared_ptr<GuidanceMachineInfo> get_received_guidance_machine_info(std::size_t index);
 
 		/// @brief Returns the content of the agricultural guidance curvature command message
 		/// based on the index of the sender. Use this to read the received messages' content.
 		/// @param[in] index An index of senders of the agricultural guidance curvature command message
 		/// @note Only one device on the bus will send this normally, but we provide a generic way to get
 		/// an arbitrary number of these commands. So generally using only index 0 will be acceptable.
+		/// @returns The content of the agricultural guidance curvature command message
 		std::shared_ptr<GuidanceSystemCommand> get_received_guidance_system_command(std::size_t index);
 
 		/// @brief Returns an event dispatcher which you can use to get callbacks when new/updated guidance machine info messages are received.