Merge pull request #56 from derskythe/docs

docs: Add extensive documentation in code comments

helpers/subbrute_radio_device_loader.h

@@ -2,14 +2,39 @@
 
 #include <lib/subghz/devices/devices.h>
 
-/** SubGhzRadioDeviceType */
+/**
+ * @file subghz_radio.h
+ * @brief Defines the Sub-GHz radio device type.
+ */
 typedef enum {
     SubGhzRadioDeviceTypeInternal,
     SubGhzRadioDeviceTypeExternalCC1101,
 } SubGhzRadioDeviceType;
 
+/**
+ * @brief Sets the SubGhz radio device type.
+ *
+ * This function is used to set the SubGhz radio device type for the SubBrute radio device loader.
+ *
+ * @param current_radio_device Pointer to the current SubGhz radio device.
+ * @param radio_device_type The desired SubGhz radio device type.
+ * @return const SubGhzDevice* Pointer to the new SubGhz radio device.
+ *
+ * @remark This function sets the SubGhz radio device type for the SubBrute radio device loader.
+ *         The current radio device will be replaced with a new instance of the specified radio device type.
+ *         If @p current_radio_device is NULL, a new instance of the specified radio device type will be created.
+ *
+ * @note The caller is responsible for handling memory deallocation of the returned pointer.
+ */
 const SubGhzDevice* subbrute_radio_device_loader_set(
     const SubGhzDevice* current_radio_device,
     SubGhzRadioDeviceType radio_device_type);
 
+/**
+ * @brief Unloads a SubGhz radio device.
+ *
+ * This function unloads a SubGhz radio device and performs any necessary cleanup.
+ *
+ * @param radio_device Pointer to the SubGhzDevice structure representing the radio device to be unloaded.
+ */
 void subbrute_radio_device_loader_end(const SubGhzDevice* radio_device);

helpers/subbrute_worker.h

@@ -3,6 +3,18 @@
 #include "../subbrute_protocols.h"
 #include "subbrute_radio_device_loader.h"
 
+/**
+ * @enum SubBruteWorkerState
+ * @brief Enumeration defining the different states of the SubBruteWorker.
+ *
+ * This enumeration defines the possible states of the SubBruteWorker, which is responsible for performing
+ * sub-brute forcing tasks.
+ *
+ * @var SubBruteWorkerStateIDLE The worker is in idle state and not performing any task.
+ * @var SubBruteWorkerStateReady The worker is ready to start a new task.
+ * @var SubBruteWorkerStateTx The worker is currently performing a sub-brute forcing task.
+ * @var SubBruteWorkerStateFinished The worker has finished the sub-brute forcing task.
+ */
 typedef enum {
     SubBruteWorkerStateIDLE,
     SubBruteWorkerStateReady,
@@ -14,17 +26,94 @@ typedef void (*SubBruteWorkerCallback)(void* context, SubBruteWorkerState state)
 
 typedef struct SubBruteWorker SubBruteWorker;
 
+/**
+ * @brief Allocates memory for a SubBruteWorker object and initializes it with the given radio_device.
+ *
+ * This function creates a new SubBruteWorker object by allocating memory for it on the heap and
+ * initializes it with the provided radio_device. The radio_device parameter must not be NULL.
+ *
+ * @param radio_device A pointer to a valid SubGhzDevice object.
+ * @return A pointer to the newly allocated SubBruteWorker object, or NULL if memory allocation failed.
+ */
 SubBruteWorker* subbrute_worker_alloc(const SubGhzDevice* radio_device);
+
+/**
+ * @brief Frees the memory associated with the given SubBruteWorker instance.
+ *
+ * This function must be called to release the resources allocated to the SubBruteWorker instance.
+ *
+ * @param instance Pointer to the SubBruteWorker instance to be freed.
+ */
 void subbrute_worker_free(SubBruteWorker* instance);
+
+/**
+ * @brief Get the current step of a sub brute force worker.
+ *
+ * @param instance A pointer to the SubBruteWorker instance.
+ * @return The current step of the sub brute force worker as a uint64_t value.
+ */
 uint64_t subbrute_worker_get_step(SubBruteWorker* instance);
+
+/**
+ * @brief Set the step value for a SubBruteWorker instance.
+ *
+ * This function sets the step value for a given SubBruteWorker instance. The step value determines the increment that
+ * will be used for each iteration in the worker's execution loop.
+ *
+ * @param instance Pointer to the SubBruteWorker instance.
+ * @param step The step value to set.
+ * @return true if the step value was successfully set, false otherwise.
+ */
 bool subbrute_worker_set_step(SubBruteWorker* instance, uint64_t step);
+
+/**
+ * @brief Check if the SubBruteWorker is currently running.
+ *
+ * @param instance Pointer to the SubBruteWorker instance.
+ *
+ * @return true if the SubBruteWorker is running, false otherwise.
+ */
 bool subbrute_worker_is_running(SubBruteWorker* instance);
+
+/**
+ * @brief Initializes a SubBruteWorker with default attack settings.
+ *
+ * This function initializes a SubBruteWorker instance with default attack settings. The attack_type parameter determines the type of attack to be performed. The step parameter specifies
+* the iteration step to be used during the attack. The protocol parameter provides the necessary protocol information for the attack. The repeats parameter specifies the number of times
+* the attack should be repeated.
+ *
+ * @param instance A pointer to a SubBruteWorker instance.
+ * @param attack_type The type of attack to be performed.
+ * @param step The iteration step to be used during the attack.
+ * @param protocol A pointer to the SubBruteProtocol structure containing protocol information.
+ * @param repeats The number of times the attack should be repeated.
+ * @return Returns true if the initialization is successful, false otherwise.
+ */
 bool subbrute_worker_init_default_attack(
     SubBruteWorker* instance,
     SubBruteAttacks attack_type,
     uint64_t step,
     const SubBruteProtocol* protocol,
     uint8_t repeats);
+
+/**
+ * @brief Initializes a file-based attack worker for the sub-brute algorithm.
+ *
+ * This function initializes a sub-brute worker to perform file-based attacks.
+ * It sets the necessary parameters for the attack, such as the attack step,
+ * the load index, the file key, the protocol to use, the number of repeats,
+ * and whether to use two bytes.
+ *
+ * @param instance A pointer to the sub-brute worker instance.
+ * @param step The attack step value to set.
+ * @param load_index The load index value to set.
+ * @param file_key The file key value to set.
+ * @param protocol The sub-brute protocol to use for the attack.
+ * @param repeats The number of times to repeat the attack.
+ * @param two_bytes A flag indicating whether to use two bytes for the attack.
+ *
+ * @return True if the initialization was successful, false otherwise.
+ */
 bool subbrute_worker_init_file_attack(
     SubBruteWorker* instance,
     uint64_t step,
@@ -33,24 +122,155 @@ bool subbrute_worker_init_file_attack(
     SubBruteProtocol* protocol,
     uint8_t repeats,
     bool two_bytes);
+
+/**
+ * @brief Start the SubBruteWorker instance.
+ *
+ * This function starts the SubBruteWorker instance, allowing it to begin its work.
+ *
+ * @param instance Pointer to the SubBruteWorker instance to start.
+ * @return Whether starting the SubBruteWorker instance was successful.
+ *     - true: Starting the SubBruteWorker instance was successful.
+ *     - false: Starting the SubBruteWorker instance failed.
+ *
+ * @note Before calling this function, make sure all the necessary inputs and configurations
+ *       have been set on the SubBruteWorker instance.
+ */
 bool subbrute_worker_start(SubBruteWorker* instance);
+
+/**
+ * @brief Stops the given SubBruteWorker instance.
+ *
+ * This function stops the SubBruteWorker instance by performing necessary clean-up operations.
+ * After calling this function, the instance is no longer usable.
+ *
+ * @param instance A pointer to the SubBruteWorker instance to stop.
+ */
 void subbrute_worker_stop(SubBruteWorker* instance);
+
+/**
+ * @brief Transmits the current key of the SubBruteWorker instance to another device.
+ *
+ * This function transmits the current key of the SubBruteWorker instance to another device
+ * using the specified step value.
+ *
+ * @param instance The pointer to the SubBruteWorker instance.
+ * @param step The step value used for transmission.
+ *
+ * @return True if the key was successfully transmitted, otherwise false.
+ */
 bool subbrute_worker_transmit_current_key(SubBruteWorker* instance, uint64_t step);
+
+/**
+ * @brief Check if the `SubBruteWorker` instance can transmit manually.
+ *
+ * This function is used to determine if the `SubBruteWorker` instance is capable of manual transmission.
+ *
+ * @param instance Pointer to the `SubBruteWorker` instance.
+ * @return `true` if the `SubBruteWorker` instance can transmit manually, `false` otherwise.
+ */
 bool subbrute_worker_can_manual_transmit(SubBruteWorker* instance);
+
+/**
+ * @brief Set the callback function and its context for the SubBruteWorker.
+ *
+ * This function allows you to set the callback function and its context for
+ * the given SubBruteWorker instance. The callback function will be called
+ * by the SubBruteWorker at specific events, providing information to the
+ * caller through the callback parameters.
+ *
+ * @param instance The SubBruteWorker instance to set the callback for.
+ * @param callback The callback function to set.
+ * @param context The context to be passed to the callback function.
+ *
+ * @note The callback function should be of the form:
+ *        void callback(SubBruteWorker* instance, void* context);
+ *      The instance parameter is the SubBruteWorker instance that triggered
+ *      the callback, while the context parameter is the user-defined context
+ *      that was set with this function.
+ *
+ * @see SubBruteWorkerCallback
+ */
 void subbrute_worker_set_callback(
     SubBruteWorker* instance,
     SubBruteWorkerCallback callback,
     void* context);
 
+/**
+ * @brief Get the timeout value of the SubBruteWorker instance.
+ *
+ * This function returns the timeout value of the SubBruteWorker instance.
+ *
+ * @param instance  Pointer to the SubBruteWorker instance.
+ *
+ * @return The timeout value as a uint8_t.
+ */
 uint8_t subbrute_worker_get_timeout(SubBruteWorker* instance);
+
+/**
+ * @brief Set the timeout for the SubBruteWorker instance.
+ *
+ * This function sets the timeout value for the SubBruteWorker instance. The timeout defines the maximum time allowed for the worker to complete its task before it is interrupted.
+ *
+ * @param instance A pointer to the SubBruteWorker instance.
+ * @param timeout The timeout value in milliseconds.
+ */
 void subbrute_worker_set_timeout(SubBruteWorker* instance, uint8_t timeout);
+
+/**
+ * @brief Retrieves the number of repeated substrings found by the SubBruteWorker instance.
+ *
+ * This function returns the count of repeated substrings found during the execution of the SubBruteWorker instance.
+ *
+ * @param instance A pointer to the SubBruteWorker instance.
+ * @return The number of repeated substrings.
+ */
 uint8_t subbrute_worker_get_repeats(SubBruteWorker* instance);
+
+/**
+ * @brief Set the number of repeats for the SubBruteWorker instance.
+ *
+ * This function sets the number of repeats for the SubBruteWorker instance. The repeats
+ * determines how many times a certain operation should be repeated.
+ *
+ * @param instance A pointer to the SubBruteWorker instance.
+ * @param repeats The number of repeats to be set.
+ */
 void subbrute_worker_set_repeats(SubBruteWorker* instance, uint8_t repeats);
+
+/**
+ * @brief Get the value of te from a SubBruteWorker instance.
+ *
+ * This function returns the value of the te member variable of the SubBruteWorker instance.
+ *
+ * @param instance A pointer to the SubBruteWorker instance.
+ * @return The value of the te member variable.
+ */
 uint32_t subbrute_worker_get_te(SubBruteWorker* instance);
+
+/**
+ * @brief Set the value of te for the SubBruteWorker instance.
+ *
+ * This function sets the value of the te member variable for the given SubBruteWorker instance.
+ * The te value determines the threshold for the worker to stop processing.
+ *
+ * @param instance Pointer to the SubBruteWorker instance
+ * @param te The threshold value to set
+ */
 void subbrute_worker_set_te(SubBruteWorker* instance, uint32_t te);
 
 // void subbrute_worker_timeout_inc(SubBruteWorker* instance);
 
 // void subbrute_worker_timeout_dec(SubBruteWorker* instance);
 
+/**
+  * @brief Checks if transmission is allowed for the given value.
+  *
+  * This function checks the transmission allowance for the given value based on the state of the SubBruteWorker instance.
+  *
+  * @param instance A pointer to the SubBruteWorker instance.
+  * @param value The value to check transmission allowance for.
+  *
+  * @return True if transmission is allowed for the given value, false otherwise.
+  */
 bool subbrute_worker_is_tx_allowed(SubBruteWorker* instance, uint32_t value);

helpers/subbrute_worker_private.h

@@ -6,6 +6,13 @@
 #include <lib/subghz/receiver.h>
 #include <lib/subghz/environment.h>
 
+/**
+ * @class SubBruteWorker
+ * @brief Class representing a SubBruteWorker object.
+ *
+ * The SubBruteWorker class is responsible for performing sub-brute forcing tasks.
+ * It manages the state, configuration and execution of the sub-brute forcing algorithm.
+ */
 struct SubBruteWorker {
     SubBruteWorkerState state;
     volatile bool worker_running;
@@ -45,6 +52,37 @@ struct SubBruteWorker {
     void* context;
 };
 
+/**
+ * @brief This function is the entry point for the sub-brute worker thread.
+ *
+ * @param context A pointer to the context data for the worker thread.
+ * @return int32_t The return status of the worker thread.
+ *
+ * The sub-brute worker thread performs a sub-brute force operation based on the given context.
+ * It takes the context as an input, processes the data, and returns a status code.
+ * The function is used as an entry point for the worker thread.
+ */
 int32_t subbrute_worker_thread(void* context);
+
+/**
+ * @brief Transmits FlipperFormat using subGHz.
+ *
+ * This function transmits the specified FlipperFormat using the subGHz
+ * protocol.
+ *
+ * @param instance The SubBruteWorker instance.
+ * @param flipper_format Pointer to the FlipperFormat to be transmitted.
+ */
 void subbrute_worker_subghz_transmit(SubBruteWorker* instance, FlipperFormat* flipper_format);
+
+/**
+ * @brief Send a callback for a SubBruteWorker instance.
+ *
+ * This function is used to send a callback for the SubBruteWorker instance. The callback is triggered
+ * when certain conditions are met during the worker's execution.
+ *
+ * @param instance The SubBruteWorker instance for which the callback is sent.
+ *
+ * @note This function does not return any values.
+ */
 void subbrute_worker_send_callback(SubBruteWorker* instance);