docs(server): 📝 replace comment by docstring for functions

server/src/commande_telephone.ino

@@ -7,7 +7,7 @@
 #include "config.h"   // Configuration des entrées/sorties et delais.
 #include "controls.h" // Fonctions pour se déplacer.
 #include "convert.h"  // Utilitaires pour convertir des mesures en steps.
-#include "server.hpp"   // Configure et demarre le server HTTP.
+#include "server.hpp" // Configure et demarre le server HTTP.
 
 // État global de la commande en cours
 command_t command = {.running = false, .stopped = false};
@@ -18,11 +18,11 @@ AsyncWebServer server(80);
 // Code exécuté au démarrage (paramétrage) :
 void setup()
 {
-  setupPins();                    // Configure les pins de l'ESP32
+  setupPins();                   // Configure les pins de l'ESP32
-  Serial.begin(115200);           // Démarrage d'une communication Série avec l'ordinateur s'il est connecté
+  Serial.begin(115200);          // Démarrage d'une communication Série avec l'ordinateur s'il est connecté
-  connectWiFi(WiFi);              // Connexion au wifi
+  connectWiFi(WiFi);             // Connexion au wifi
-  serverConfig(server, command);  // Configuration du serveur
+  serverConfig(server, command); // Configuration du serveur
-  server.begin();                 // Démarrage du serveur
+  server.begin();                // Démarrage du serveur
 }
 
 // Code exécuté en boucle jusqu'à l'extinction du robot
@@ -54,6 +54,7 @@ void loop()
   }
 }
 
+// Met à jour l'état du robot en fonction de la commande en cours.
 void updateCommand(command_t &command)
 {
   if (command.name == "forward")

server/src/controls.h

@@ -2,7 +2,10 @@
  Initialisation et fonctions de déplacement
 *******************************************/
 
-// Configure les ports de contrôle des moteurs sont des sorties (output)
+/**
+ * @brief Configure les ports de contrôle des moteurs sont des sorties (output).
+ *
+ */
 void setupPins()
 {
     pinMode(IN1a, OUTPUT);
@@ -16,9 +19,18 @@ void setupPins()
     pinMode(IN4b, OUTPUT);
 }
 
-// Applique une configuration aux moteurs.
+/**
-// Chaque configuration est sur 1 octet.
+ * @brief Applique une configuration aux moteurs.
-// ex: writeMotor(0b0010, 0b1100);
+ * @brief Chaque configuration est sur 1 octet.
+ *
+ * Exemple
+ * ```
+ * writeMotor(0b0010, 0b1100);
+ * ```
+ *
+ * @param left Configuration du moteur droit (ex: `0b1100`).
+ * @param right Configuration du moteur droit (ex: `0b0101`).
+ */
 void writeMotor(uint8_t left, uint8_t right)
 {
     digitalWrite(IN4a, left & 0b1000);
@@ -31,7 +43,10 @@ void writeMotor(uint8_t left, uint8_t right)
     digitalWrite(IN1b, right & 0b0001);
 }
 
-// Commande pour faire avancer le robot.
+/**
+ * @brief Commande pour faire avancer le robot.
+ *
+ */
 void forward()
 {
     writeMotor(0b1000, 0b0001);
@@ -44,7 +59,10 @@ void forward()
     delay(DELAY_TIME);
 }
 
-// Commande pour faire reculer le robot.
+/**
+ * @brief Commande pour faire reculer le robot.
+ *
+ */
 void backward()
 {
     writeMotor(0b0001, 0b1000);
@@ -57,7 +75,10 @@ void backward()
     delay(DELAY_TIME);
 }
 
-// Commande pour faire tourner le robot à droite.
+/**
+ * @brief Commande pour faire tourner le robot à droite.
+ *
+ */
 void right()
 {
     writeMotor(0b1000, 0b1000);
@@ -70,7 +91,10 @@ void right()
     delay(DELAY_TIME);
 }
 
-// Commande pour faire tourner le robot à gauche.
+/**
+ * @brief Commande pour faire tourner le robot à gauche.
+ *
+ */
 void left()
 {
     writeMotor(0b0001, 0b0001);
@@ -83,8 +107,11 @@ void left()
     delay(DELAY_TIME);
 }
 
-// Commande pour arrêter les  moteurs du robot.
+/**
-void stopMotors(void)
+ * @brief Commande pour arrêter les  moteurs du robot.
+ *
+ */
+void stopMotors()
 {
     writeMotor(0b0000, 0b0000);
 }

server/src/convert.h

@@ -2,20 +2,36 @@
  Utilitaires de conversions physique -> steps
 *********************************************/
 
-// Convertit une longueur en cm vers un nombre de pas moteur.
+/**
-// ex:
+ * @brief Convertit une longueur en cm vers un nombre de pas moteur.
-// float distance = 22.3; //cm
+ *
-// int steps = convertLengthToSteps(distance);
+ * Exemple
+ * ```
+ * float distance = 22.3; //cm
+ * int steps = convertLengthToSteps(distance);
+ * ```
+ *
+ * @param length
+ * @return int
+ */
 int convertLengthToSteps(float length)
 {
     float result = length * 512 / (4 * 3.1415);
     return int(result);
 }
 
-// Convertit une rotation en degrés vers un nombre de pas moteur.
+/**
-// ex:
+ * @brief Convertit une rotation en degrés vers un nombre de pas moteur.
-// float angle = 45; //deg
+ *
-// int steps = convertRotToSteps(angle);
+ * Exemple
+ * ```
+ * float angle = 45; //deg
+ * int steps = convertRotToSteps(angle);
+ * ```
+ *
+ * @param rotation Angle en degrés.
+ * @return int Nombres de pas pour les moteurs.
+ */
 int convertRotToSteps(int rotation)
 {
     int result = convertLengthToSteps(rotation * 3.1415 / 180 * 7.8);

server/src/server.hpp

@@ -2,7 +2,10 @@
  Configuration et handlers du server
 ************************************/
 
-// Type de la variable globale command
+/**
+ * @brief Type de la variable globale command
+ *
+ */
 struct command_t
 {
     bool running; // Une commande doit être exécutée
@@ -11,7 +14,14 @@ struct command_t
     int value;    // Valeur (nombre de pas à effectuer)
 };
 
-// Met à jour la command globale.
+/**
+ * @brief Met à jour la command globale.
+ * @internal
+ *
+ * @param commandName Nom de la nouvelle commande.
+ * @param commandValue Valeur de la nouvelle commande.
+ * @param globalCommand Commande globale (courante).
+ */
 void setGlobals(String commandName, float commandValue, command_t &globalCommand)
 {
     // Assert command before updating globals
@@ -54,12 +64,20 @@ void requestCheck(String commandName, float commandValue, command_t &globalComma
 }
 
 /**
- * Parse la requête GET (vers "/get") du serveur et résout le nom de la commande et sa valeur.
+ * @brief Parse la requête GET (vers "/get") du serveur et résout le nom de la commande et sa valeur.
+ *
+ * Exemple :
+ * ```
+ * String commandName;
+ * float commandValue;
+ * parseRequestParams(request, commandName, commandValue);
+ * ```
+ *
+ * @param request Requête contenant la commande.
+ * @param commandName Nom de la commande à assigner.
+ * @param commandValue Valeur de la commande à assigner.
+ * @param globalCommand Commande globale (courante) à mettre à jour.
  *
- * Example
- *     String commandName;
- *     float commandValue;
- *     parseRequestParams(request, commandName, commandValue);
  */
 void parseRequestParams(AsyncWebServerRequest *request, String &commandName, float &commandValue, command_t &globalCommand)
 {
@@ -79,7 +97,12 @@ void parseRequestParams(AsyncWebServerRequest *request, String &commandName, flo
     requestCheck(commandName, commandValue, globalCommand);
 }
 
-// Configuration du serveur asynchrone.
+/**
+ * @brief Configuration du serveur asynchrone.
+ *
+ * @param server Serveur à configurer.
+ * @param globalCommand Commande globale (courante) à mettre à jour lors des requêtes.
+ */
 void serverConfig(AsyncWebServer &server, command_t &globalCommand)
 {
     server.on("/get", HTTP_GET, [&globalCommand](AsyncWebServerRequest *request)
@@ -96,7 +119,11 @@ void serverConfig(AsyncWebServer &server, command_t &globalCommand)
     request->send(200, "text/plain", commandName); });
 }
 
-// Démarre le point d'accès WiFi.
+/**
+ * @brief Démarre le point d'accès WiFi.
+ *
+ * @param WiFi WiFi à configurer.
+ */
 void connectWiFi(WiFiClass &WiFi)
 {
     // For simulator only