From 86475b11535b7c6797dde98e9dea0914b20fad7a Mon Sep 17 00:00:00 2001
From: Stefano Calabretti <StefanoCalabretti@outlook.it>
Date: Wed, 23 Feb 2022 18:50:53 +0100
Subject: [PATCH] Improve docs

---
 Inc/mmr_can.h             | 54 +++++++++++++++++++++++++++++++++++++--
 Inc/mmr_can_events.h      |  8 ++++++
 Inc/mmr_can_scs_manager.h |  7 +----
 Src/mmr_can.c             |  2 +-
 Src/mmr_can_events.c      |  8 +-----
 5 files changed, 63 insertions(+), 16 deletions(-)

diff --git a/Inc/mmr_can.h b/Inc/mmr_can.h
index b68e16c..cd9cbec 100644
--- a/Inc/mmr_can.h
+++ b/Inc/mmr_can.h
@@ -177,14 +177,64 @@ typedef struct {
 extern MmrCanTickProvider __mmr_can_tickProvider;
 
 
-void MMR_CAN_Init(MmrCanTickProvider tickProvider);
+/**
+ * @brief
+ * Sets the tick provider.
+ * 
+ * @param tickProvider
+ *  The function to use when fetching the current tick.
+ */
+void MMR_CAN_SetTickProvider(MmrCanTickProvider tickProvider);
+
+/**
+ * @brief
+ * Configures the filters with the default configuration
+ * and starts the can interface.
+ */
 HalStatus MMR_CAN_BasicSetupAndStart(CanHandle *hcan);
+
+/**
+ * @brief
+ * Configures the filters.
+ * 
+ * @param hcan The interface to use.
+ * @param settings The settings to use when configuring the filters.
+ * @return HalStatus The result of the operation.
+ */
 HalStatus MMR_CAN_FilterConfig(CanHandle *hcan, MmrCanFilterSettings settings);
-CanFilterMask MMR_CAN_AlignStandardMask(CanFilterMask baseMask);
+
+/**
+ * @brief
+ * Provides the default configuration for
+ * the filters. 
+ */
 MmrCanFilterSettings MMR_CAN_GetDefaultFilterSettings();
 
+/**
+ * @brief
+ * Sends a can packet over the network.
+ * Based on the data length, the packet may be split
+ * into multiple frames.
+ * 
+ * It is not recommended to send more than 8 bytes, as the
+ * 'multiple frames' feature has not been fully implemented yet.
+ */
 HalStatus MMR_CAN_Send(CanHandle *hcan, MmrCanPacket packet);
+
+/**
+ * @brief
+ * Sends a can packet over the network as is, without
+ * changing the data that is provided.
+ * 
+ * This can prevent the sudden change of the header's message type when
+ * using MMR_CAN_Send.
+ */
 HalStatus MMR_CAN_SendNoTamper(CanHandle *hcan, MmrCanPacket packet);
+
+/**
+ * @brief
+ * Receives a can message from the network.
+ */
 HalStatus MMR_CAN_Receive(CanHandle *hcan, MmrCanMessage *result);
 
 #endif /* INC_MMR_CAN_H_ */
diff --git a/Inc/mmr_can_events.h b/Inc/mmr_can_events.h
index be7cd88..6b4a6d2 100644
--- a/Inc/mmr_can_events.h
+++ b/Inc/mmr_can_events.h
@@ -25,6 +25,14 @@ typedef struct {
 #define MMR_CAN_CreateEventList(handlers) \
   (const MmrCanEventList) { handlers, sizeofarray(handlers) }
 
+
+/**
+ * @brief
+ * Activates the CAN rx interrupts
+ *
+ * When one is fired, the callbacks provided inside the
+ * MmrCanEventList will be invoked
+ */
 HalStatus MMR_CAN_InitRxHandlers(CanHandle *hcan, const MmrCanEventList *rxEvents);
 
 
diff --git a/Inc/mmr_can_scs_manager.h b/Inc/mmr_can_scs_manager.h
index e72f2e9..08a1b32 100644
--- a/Inc/mmr_can_scs_manager.h
+++ b/Inc/mmr_can_scs_manager.h
@@ -115,7 +115,6 @@ bool MMR_CAN_MaybeHandleAck(MmrCanHeader header);
  * 
  * This function MUST be called at every loop.
  * 
- * @param hcan The interface to use.
  * @return HalStatus
  *  The result of the operation.
  *  HAL_ERROR should immediately be handled as a safe state.
@@ -127,9 +126,7 @@ HalStatus MMR_CAN_HandleNextScs(CanHandle *hcan);
  * Send an acknowledgment packet based on the
  * given scs header.
  * 
- * @param hcan The can interface to use.
- * @param originalHeader The scs header to acknowledge. 
- * @return HalStatus The result of the operation.
+ * @param originalHeader The scs header to acknowledge.
  */
 HalStatus MMR_CAN_SendAck(
   CanHandle *hcan,
@@ -140,10 +137,8 @@ HalStatus MMR_CAN_SendAck(
  * @brief
  * Sends an Scs message.
  * 
- * @param hcan The can interface to use.
  * @param scsId The MMR_CAN_MESSAGE_ID_SCS_xx id.
  * @param senderId The id of this board.
- * @return HalStatus The result of the operation.
  */
 HalStatus MMR_CAN_SendScs(
   CanHandle *hcan,
diff --git a/Src/mmr_can.c b/Src/mmr_can.c
index 0a59c9c..e9b1991 100644
--- a/Src/mmr_can.c
+++ b/Src/mmr_can.c
@@ -5,7 +5,7 @@
 MmrCanTickProvider __mmr_can_tickProvider;
 
 
-void MMR_CAN_Init(MmrCanTickProvider tickProvider) {
+void MMR_CAN_SetTickProvider(MmrCanTickProvider tickProvider) {
   __mmr_can_tickProvider = tickProvider;
 }
 
diff --git a/Src/mmr_can_events.c b/Src/mmr_can_events.c
index 5e0a3f9..1fe9e09 100644
--- a/Src/mmr_can_events.c
+++ b/Src/mmr_can_events.c
@@ -10,13 +10,7 @@ static void __invokeAll(const MmrCanEventList *events, const MmrCanMessage *even
 static void __maybeInvoke(const MmrCanEventHandler handler, const MmrCanMessage *event);
 
 
-/**
- * @brief
- * Activates the CAN rx interrupts
- *
- * When one is fired, the callbacks provided inside the
- * MmrCanEventList will be invoked
- */
+
 HalStatus MMR_CAN_InitRxHandlers(CanHandle *hcan, const MmrCanEventList *rxEvents) {
   _rxEvents = rxEvents;
   return HAL_CAN_ActivateNotification(hcan, MMR_CAN_RX_INTERRUPT);