Improve documentation

Author: sebromero

src/Folder.cpp

@@ -16,8 +16,7 @@ Folder::Folder(const char* path) {
         int result = mkdir(path, S_IRWXU | S_IRWXG | S_IRWXO);
         if (result == 0) {
             this->path = std::string(path);
-
-        } // else ...not sure about this one yet
+        }
     }
 }
 

src/Folder.h

@@ -15,18 +15,23 @@ class Folder {
 
   public:
     /**
-     * @brief Blank Constructor.
+     * @brief Creates an empty Folder object. 
+     * Please note that any operation on this object will fail until a valid directory is assigned to it.
      */
     Folder();
 
     /**
-     * @brief Constructor.
+     * @brief Creates a directory with the specified name.
+     * If the directory already exists, it returns a Folder object representing the existing directory.
+     * Otherwise, it tries to create a new directory with the specified name. If it failes the `path` property of the Folder object will be null.
      * @param const char * dirname - The name of the directory.
      */
     Folder(const char * dirname);
 
     /**
-     * @brief Constructor.
+     * @brief Creates a directory with the specified name.
+     * If the directory already exists, it returns a Folder object representing the existing directory.
+     * Otherwise, it tries to create a new directory with the specified name. If it failes the `path` property of the Folder object will be empty.
      * @param String dirname - The name of the directory.
      */
     Folder(String dirname);

src/InternalStorage.cpp

@@ -33,12 +33,11 @@ bool InternalStorage::partition(){
     Partitioning::partitionDrive(QSPIFBlockDeviceType::get_default_instance(), {{QSPI_STORAGE_SIZE, FS_LITTLEFS}});
 }
 
-
 bool InternalStorage::restoreDefaultPartitions(){
     Partitioning::partitionDrive(QSPIFBlockDeviceType::get_default_instance(), {
-        {1024, FS_FAT},
-        {5120, FS_FAT},
-        {8192, FS_LITTLEFS}
+        {1024, FS_FAT}, // 1 MB for certificates
+        {5120, FS_FAT}, // 5 MB for OTA firmware updates
+        {8192, FS_LITTLEFS} // 8 MB for user data
     });
 }
 

src/Partitioning.h

@@ -35,29 +35,57 @@ struct __attribute__((packed)) mbrTable {
 class Partitioning{
     public:
         /**
-         * This method erases the first block (4096 bytes) of the BlockDevice to delete any already existing MBR partition table
+         * Erases the first block (4096 bytes) of the BlockDevice to delete any already existing MBR partition table
          * @param The BlockDevice on which the MBR sector is situated.
          * @returns True upon success, False on failure
         */
         static bool eraseMBRSector(BlockDeviceType * blockDevice);
 
         /**
-         * This method partitions the BlockDevice according to the partitioning schemme given by the vector of Partition structs
+         * Partitions the BlockDevice according to the partitioning schemme given by the vector of Partition structs
          * @param blockDevice - the BlockDevice which we would like to partition.
          * @param partitions - a vector of Partition structs that represents the partitioning scheme 
          * @returns True upon success, False on failure
         */
         static bool partitionDrive(BlockDeviceType * blockDevice, std::vector<Partition> partitions);
 
         /**
-         * This method reads and unpacks the MBR partition information and returns a list of partitions it can find on the drive
+         * Reads and unpacks the MBR partition information and returns a list of partitions it can find on the drive
          * @param  blockDevice on which the MBR sector is situated.
          * @returns std::vector of Partition containing size and filesystem information about each partition
         */
         static std::vector<Partition> readPartitions(BlockDeviceType * blockDevice);
     private:
+        /**
+         * Checks if the given partition scheme is valid for the specified block device.
+         * It does that by checking if the sum of the partition sizes is equal to the size of the block device and
+         * by ensuring that there are a maximum of 4 partitions.
+         *
+         * @param blockDevice The block device to check the partition scheme against.
+         * @param partitions The partition scheme to check for validity.
+         * @return True if the partition scheme is valid for the block device, false otherwise.
+         */
         static bool isPartitionSchemeValid(BlockDeviceType * blockDevice, std::vector<Partition> partitions);
+        
+        
+        /**
+         * Formats the specified partition of the given block device with the specified file system type.
+         *
+         * @param blockDevice The block device to format the partition on.
+         * @param partitionNumber The number of the partition to format.
+         * @param fileSystemType The file system type to format the partition with.
+         * @return True if the partition was formatted successfully, false otherwise.
+         */
         static bool formatPartition(BlockDeviceType * blockDevice, int partitionNumber, FileSystems fileSystemType);
+        
+        /**
+         * Creates and formats partitions on the specified block device.
+         * The partitioning splits the block device into partitions of the specified sizes and formats them with the specified file system types.
+         *
+         * @param blockDevice Pointer to the block device to partition and format.
+         * @param partitions Vector of Partition objects representing the partitions to create and format.
+         * @return True if all partitions were successfully created and formatted, false otherwise.
+         */
         static bool createAndFormatPartitions(BlockDeviceType * blockDevice, std::vector<Partition> partitions);
 
 };

src/USBStorage.h

@@ -4,8 +4,10 @@
 #define USBStorage_H
 
 #include "Arduino_UnifiedStorage.h"
+
 /**
- * Represents a USB storage using the Arduino Unified Storage library.
+ * USBStorage class provides an interface to access USB storage devices.
+ * It inherits from the Arduino_UnifiedStorage class and implements its pure virtual functions.
  */
 class USBStorage : public Arduino_UnifiedStorage {
 public:
@@ -58,12 +60,30 @@ class USBStorage : public Arduino_UnifiedStorage {
      */
     bool isMounted();
 
+    /**
+     * Sets the callback function to be called when a USB connection is established.
+     *
+     * @param callbackFunction A pointer to the function to be called when a USB connection is established.
+     */
     void onConnect(void (* const callbackFunction)());
 
+    /**
+     * @brief Removes the callback function that is executed when the USB storage device is connected.
+     * 
+     */
     void removeOnConnectCallback();
 
+    /**
+     * @brief Sets a callback function to be called when the USB storage device is disconnected.
+     * 
+     * @param callbackFunction A pointer to the function to be called when the USB storage device is disconnected.
+     */
     void onDisconnect(void (* const callbackFunction)());
 
+    /**
+     * @brief Removes the callback function that is called when the USB storage device is disconnected.
+     * 
+     */
     void removeOnDisconnectCallback();