Documentaton generation completed

esp_modem/include/cxx_include/esp_modem_api.hpp

@@ -26,9 +26,6 @@ struct esp_modem_dce_config;
 namespace esp_modem {
 
 class DTE;
-using dce_config = ::esp_modem_dce_config;
-using dte_config = ::esp_modem_dte_config;
-
 typedef struct esp_netif_obj esp_netif_t;
 
 
@@ -40,6 +37,9 @@ typedef struct esp_netif_obj esp_netif_t;
 * @{
 */
 
+using dce_config = ::esp_modem_dce_config;
+using dte_config = ::esp_modem_dte_config;
+
 /**
  * @brief Create UART DTE
  * @param config DTE configuration
@@ -52,7 +52,7 @@ std::shared_ptr<DTE> create_uart_dte(const dte_config *config);
 
 /**
  * @defgroup ESP_MODEM_INIT_DCE ESP_MODEM Initialization API for DCE
- * @brief Create DCE's
+ * @brief ESP_MODEM Initialization API for DCE
  */
 /** @addtogroup ESP_MODEM_INIT_DCE
 * @{

esp_modem/include/cxx_include/esp_modem_cmux.hpp

@@ -49,6 +49,10 @@ enum class cmux_state {
  */
 class CMuxInstance;
 
+/**
+ * @brief CMux class which consumes the original terminal and creates multiple virtual terminals from it.
+ * This class is not usable applicable as a DTE terminal
+ */
 class CMux {
 public:
     explicit CMux(std::unique_ptr<Terminal> t, std::unique_ptr<uint8_t[]> b, size_t buff_size):
@@ -77,6 +81,10 @@ private:
     int instance;
 };
 
+/**
+ * @brief This represents a specific instance of a CMUX virtual terminal. This class also implements Terminal interface
+ * and as such could be used as a DTE's terminal.
+ */
 class CMuxInstance: public Terminal {
 public:
     explicit CMuxInstance(std::shared_ptr<CMux> parent, int i): cmux(std::move(parent)), instance(i) {}

esp_modem/include/cxx_include/esp_modem_dce.hpp

@@ -21,6 +21,18 @@
 
 namespace esp_modem {
 
+/**
+ * @defgroup ESP_MODEM_DCE
+ * @brief Definition of DCE abstraction
+ */
+/** @addtogroup ESP_MODEM_DCE
+ * @{
+ */
+
+
+/**
+ * @brief Helper class responsible for switching modes of the DCE's
+ */
 class DCE_Mode {
 public:
     DCE_Mode(): mode(modem_mode::COMMAND_MODE) {}
@@ -33,7 +45,10 @@ private:
 
 };
 
-
+/**
+ * @brief General DCE class templated on a specific module. It is responsible for all the necessary transactions
+ * related to switching modes and consequent synergy with aggregated objects of DTE, Netif and a specific Module
+ */
 template<class SpecificModule>
 class DCE_T {
     static_assert(std::is_base_of<ModuleIf, SpecificModule>::value, "DCE must be instantiated with Module class only");
@@ -72,7 +87,10 @@ protected:
     DCE_Mode mode;
 };
 
-
+/**
+ * @brief Common abstraction of the modem DCE, specialized by the GenericModule which is a parent class for the supported
+ * defices and most common modems, as well.
+ */
 class DCE: public DCE_T<GenericModule> {
 public:
 
@@ -90,6 +108,10 @@ public:
 
 };
 
+/**
+ * @}
+ */
+
 } // esp_modem
 
 #endif // _ESP_MODEM_DCE_HPP_

esp_modem/include/cxx_include/esp_modem_dce_factory.hpp

@@ -15,10 +15,24 @@
 #ifndef _ESP_MODEM_DCE_FACTORY_HPP_
 #define _ESP_MODEM_DCE_FACTORY_HPP_
 
+/**
+ * @defgroup ESP_MODEM_DCE_FACTORY
+ * @brief DCE modem factory
+ */
+
+
 namespace esp_modem::dce_factory {
 
 using config = ::esp_modem_dce_config;
 
+/** @addtogroup ESP_MODEM_DCE_FACTORY
+* @{
+*/
+
+
+/**
+ * @brief Helper class for creating a uder define pointer in a specific way, either as a plain pointer, shared_ptr or unique_ptr
+ */
 class FactoryHelper {
 public:
     static std::unique_ptr<PdpContext> create_pdp_context(std::string &apn);
@@ -43,6 +57,9 @@ public:
 
 };
 
+/**
+ * @brief Builder class for building a DCE_T<Module> in a specific way, either form a Module object or by default from the DTE and netif
+ */
 template<typename Module>
 class Builder {
     static_assert(std::is_base_of<ModuleIf, Module>::value, "Builder must be used only for Module classes");
@@ -87,23 +104,46 @@ private:
     esp_netif_t *netif;
 };
 
+/**
+ * @brief Specific modem choice when creating by the Factory
+ */
 enum class Modem {
-    SIM800,
-    SIM7600,
-    BG96,
-    MinModule
+    GenericModule,      /*!< Default generic module with the most common commands */
+    SIM800,             /*!< Derived from the GenericModule with specifics applied to SIM800 model */
+    SIM7600,            /*!< Derived from the GenericModule, specifics applied to SIM7600 model */
+    BG96,               /*!< Derived from the GenericModule, specifics applied to BG69 model */
 };
 
+/**
+ * @brief Factory class for creating virtual DCE objects based on the configuration of the supplied module.
+ * This could also be used to create a custom module or a DCE_T<module>, provided user app derives from this factory.
+ */
 class Factory {
 public:
     explicit Factory(Modem modem): m(modem) {}
 
+    /**
+     * @brief Create a default unique_ptr DCE in a specific way (from the module)
+     * @tparam Module Specific Module used in this DCE
+     * @tparam Args Arguments to the builder, i.e. constructor of esp_modem::DCE_T class
+     * @param cfg DCE configuration structure ::esp_modem_dte_config
+     * @param args typically a DTE object and a netif handle for PPP network
+     * @return unique_ptr DCE of the created DCE on success
+     */
     template <typename Module, typename ...Args>
     static std::unique_ptr<DCE> build_unique(const config *cfg, Args&&... args)
     {
         return build_generic_DCE<Module, DCE, std::unique_ptr<DCE>>(cfg, std::forward<Args>(args)...);
     }
 
+    /**
+     * @brief Create a DCE
+     * @tparam Module Specific Module used in this DCE
+     * @tparam Args Arguments to the builder, i.e. constructor of esp_modem::DCE_T class
+     * @param cfg DCE configuration structure ::esp_modem_dte_config
+     * @param args typically a DTE object and a netif handle for PPP network
+     * @return DCE pointer the created DCE on success
+     */
     template <typename Module, typename ...Args>
     static DCE* build(const config *cfg, Args&&... args)
     {
@@ -128,12 +168,21 @@ public:
                 return build_shared_module<SIM7600>(cfg, std::forward<Args>(args)...);
             case Modem::BG96:
                 return build_shared_module<BG96>(cfg, std::forward<Args>(args)...);
-            case Modem::MinModule:
+            case Modem::GenericModule:
+                return build_shared_module<GenericModule>(cfg, std::forward<Args>(args)...);
+            default:
                 break;
         }
         return nullptr;
     }
 
+    /**
+     * @brief Create a default unique_ptr DCE generically, with the chosen module derived from the GenericModule
+     * @tparam Args Arguments to the builder, i.e. constructor of esp_modem::DCE_T class
+     * @param cfg DCE configuration structure ::esp_modem_dte_config
+     * @param args typically a DTE object and a netif handle for PPP network
+     * @return unique_ptr DCE of the created DCE on success
+     */
     template <typename ...Args>
     std::unique_ptr<DCE> build_unique(const config *cfg, Args&&... args)
     {
@@ -144,7 +193,9 @@ public:
                 return build_unique<SIM7600>(cfg, std::forward<Args>(args)...);
             case Modem::BG96:
                 return build_unique<BG96>(cfg, std::forward<Args>(args)...);
-            case Modem::MinModule:
+            case Modem::GenericModule:
+                return build_unique<GenericModule>(cfg, std::forward<Args>(args)...);
+            default:
                 break;
         }
         return nullptr;
@@ -169,6 +220,11 @@ protected:
     }
 };
 
+/**
+ * @}
+ */
+
 } // namespace esp_modem::dce_factory
 
+
 #endif // _ESP_MODEM_DCE_FACTORY_HPP_

esp_modem/include/cxx_include/esp_modem_dce_module.hpp

@@ -24,10 +24,23 @@
 
 namespace esp_modem {
 
+/**
+ * @defgroup ESP_MODEM_MODULE
+ * @brief Definition of modules representing specific modem devices
+ */
+
+/** @addtogroup ESP_MODEM_MODULE
+* @{
+*/
+
 enum class command_result;
 class DTE;
 struct PdpContext;
 
+/**
+ * @brief This is a basic building block for custom modules as well as for the supported modules in the esp-modem component
+ * It derives from the ModuleIf.
+ */
 class GenericModule: public ModuleIf {
 public:
     explicit GenericModule(std::shared_ptr<DTE> dte, std::unique_ptr<PdpContext> pdp):
@@ -72,24 +85,37 @@ protected:
 };
 
 // Definitions of other modules
+
+/**
+ * @brief Specific definition of the SIM7600 module
+ */
 class SIM7600: public GenericModule {
     using GenericModule::GenericModule;
 public:
     command_result get_module_name(std::string& name) override;
 };
 
+/**
+ * @brief Specific definition of the SIM800 module
+ */
 class SIM800: public GenericModule {
     using GenericModule::GenericModule;
 public:
     command_result get_module_name(std::string& name) override;
 };
 
+/**
+ * @brief Specific definition of the BG96 module
+ */
 class BG96: public GenericModule {
     using GenericModule::GenericModule;
 public:
     command_result get_module_name(std::string& name) override;
 };
 
+/**
+ * @}
+ */
 
 } // namespace esp_modem
 

esp_modem/include/cxx_include/esp_modem_dte.hpp

@@ -26,14 +26,37 @@
 
 namespace esp_modem {
 
+/**
+ * @defgroup ESP_MODEM_DTE
+ * @brief Definition of DTE and related classes
+ */
+/** @addtogroup ESP_MODEM_DTE
+* @{
+*/
+
+/**
+ * DTE (Data Terminal Equipment) class
+ */
 class DTE : public CommandableIf {
 public:
     explicit DTE(std::unique_ptr<Terminal> t);
 
     ~DTE() = default;
 
+    /**
+     * @brief Writing to the underlying terminal
+     * @param data Data pointer to write
+     * @param len Data len to write
+     * @return number of bytes written
+     */
     int write(uint8_t *data, size_t len) { return term->write(data, len); }
 
+    /**
+     * @brief Reading from the underlying terminal
+     * @param d Returning the data pointer of the received payload
+     * @param len Length of the data payload
+     * @return number of bytes read
+     */
     int read(uint8_t **d, size_t len) {
         auto data_to_read = std::min(len, buffer_size);
         auto data = buffer.get();
@@ -92,6 +115,9 @@ private:
     std::function<bool(uint8_t *data, size_t len)> on_data;
 };
 
+/**
+ * @}
+ */
 
 } // namespace esp_modem
 

esp_modem/include/cxx_include/esp_modem_netif.hpp

@@ -30,16 +30,37 @@ struct ppp_netif_driver {
     Netif *ppp;
 };
 
+/**
+ * @defgroup ESP_MODEM_NETIF
+ * @brief Network interface layer of the esp-modem
+ */
+
+/** @addtogroup ESP_MODEM_NETIF
+* @{
+*/
+
+/**
+ * @brief Network interface class responsible to glue the esp-netif to the modem's DCE
+ */
 class Netif {
 public:
     explicit Netif(std::shared_ptr<DTE> e, esp_netif_t *netif);
 
     ~Netif();
 
+    /**
+     * @brief Start the network interface
+     */
     void start();
 
+    /**
+     * @brief Blocks until the network interface closes
+     */
     void wait_until_ppp_exits();
 
+    /**
+     * @brief Stop the network interface
+     */
     void stop();
 
 private:
@@ -59,6 +80,10 @@ private:
     static const size_t PPP_EXIT = signal_group::bit1;
 };
 
+/**
+ * @}
+ */
+
 } // namespace esp_modem
 
 #endif // _ESP_MODEM_NETIF_HPP

esp_modem/include/cxx_include/esp_modem_terminal.hpp

@@ -26,37 +26,64 @@
 
 namespace esp_modem {
 
+/**
+ * @defgroup ESP_MODEM_TERMINAL
+ * @brief Definition of an abstract terminal to be attached to DTE class
+ */
+
+/** @addtogroup ESP_MODEM_TERMINAL
+* @{
+*/
+
+/**
+ * @brief Terminal errors
+ */
 enum class terminal_error {
     BUFFER_OVERFLOW,
     CHECKSUM_ERROR,
     UNEXPECTED_CONTROL_FLOW,
 };
 
+/**
+ * @brief Terminal interface. All communication interfaces must comply this interface in order to be used as a DTE
+ */
 class Terminal {
 public:
     virtual ~Terminal() = default;
 
-//    virtual void set_data_cb(std::function<bool(size_t len)> f) { on_data = std::move(f); }
-
     void set_error_cb(std::function<void(terminal_error)> f) { on_error = std::move(f); }
+
     virtual void set_read_cb(std::function<bool(uint8_t *data, size_t len)> f) { on_data = std::move(f); }
 
+    /**
+     * @brief Writes data to the terminal
+     * @param data Data pointer
+     * @param len Data len
+     * @return length of data written
+     */
     virtual int write(uint8_t *data, size_t len) = 0;
 
+    /**
+     * @brief Read from the terminal. This function doesn't block, but return all available data.
+     * @param data Data pointer to store the read payload
+     * @param len Maximum data len to read
+     * @return length of data actually read
+     */
     virtual int read(uint8_t *data, size_t len) = 0;
 
     virtual void start() = 0;
 
     virtual void stop() = 0;
 
-    virtual size_t max_virtual_terms() { return 1; }
-
 protected:
-//    std::function<bool(size_t len)> on_data;
     std::function<bool(uint8_t *data, size_t len)> on_data;
     std::function<void(terminal_error)> on_error;
 };
 
+/**
+ * @}
+ */
+
 } // namespace esp_modem
 
 #endif // _ESP_MODEM_TERMINAL_HPP_

esp_modem/include/cxx_include/esp_modem_types.hpp

@@ -22,21 +22,40 @@
 
 namespace esp_modem {
 
+/**
+ * @defgroup ESP_MODEM_TYPES
+ * @brief Basic type definitions used in esp-modem
+ */
+
+/** @addtogroup ESP_MODEM_TYPES
+* @{
+*/
+
+/**
+ * @brief Modem working mode
+ */
 enum class modem_mode {
     UNDEF,
-    COMMAND_MODE,
-    DATA_MODE,
-    CMUX_MODE
+    COMMAND_MODE, /*!< Command mode -- the modem is supposed to send AT commands in this mode  */
+    DATA_MODE,    /*!< Data mode -- the modem communicates with network interface on PPP protocol */
+    CMUX_MODE     /*!< CMUX (Multiplex mode) -- Simplified CMUX mode, which creates two virtual terminals,
+                   *  assigning one solely to command interface and the other  to the data mode */
 };
 
+/**
+ * @brief Module command result
+ */
 enum class command_result {
-    OK,
-    FAIL,
-    TIMEOUT
+    OK,             /*!< The command completed successfully */
+    FAIL,           /*!< The command explicitly failed */
+    TIMEOUT         /*!< The device didn't respond in the specified timeline */
 };
 
 typedef std::function<command_result(uint8_t *data, size_t len)> got_line_cb;
 
+/**
+ * @brief PDP context used for configuring and setting the data mode up
+ */
 struct PdpContext {
     explicit PdpContext(std::string apn) : apn(std::move(apn)) {}
     size_t context_id = 1;
@@ -44,18 +63,44 @@ struct PdpContext {
     std::string apn;
 };
 
+/**
+ * @brief Interface for classes eligible to send AT commands (Modules, DCEs, DTEs)
+ */
 class CommandableIf {
 public:
+    /**
+     * @brief Sends custom AT command
+     * @param command Command to be sent
+     * @param got_line callback if a line received
+     * @param time_ms timeout in milliseconds
+     * @return OK, FAIL or TIMEOUT
+     */
     virtual command_result command(const std::string &command, got_line_cb got_line, uint32_t time_ms) = 0;
 };
 
+/**
+ * @brief Interface for classes implementing a module for the modem
+ */
 class ModuleIf {
 public:
+    /**
+     * @brief Sets the data mode up (provides the necessary configuration to connect to the cellular network
+     * @return true on success
+     */
     virtual bool setup_data_mode() = 0;
 
+    /**
+     * @brief Sets the operation mode
+     * @param mode Desired mode
+     * @return true on success
+     */
     virtual bool set_mode(modem_mode mode) = 0;
 };
 
+/**
+ * @}
+ */
+
 } // namespace esp_modem
 
 #endif // _ESP_MODEM_TYPES_HPP_