Added simple docs sketch

esp_modem/include/cxx_include/esp_modem_dce.hpp

@@ -44,6 +44,9 @@ public:
 
     ~DCE_T() = default;
 
+    /**
+     * @brief Set data mode!
+     */
     void set_data() { set_mode(modem_mode::DATA_MODE); }
 
     void exit_data() { set_mode(modem_mode::COMMAND_MODE); }

esp_modem/include/esp_modem_c_api_types.h

@@ -24,17 +24,53 @@ extern "C" {
 typedef struct esp_modem_dce_wrap esp_modem_dce_t;
 
 struct PdpContext;
+
+/**
+ * @defgroup ESP_MODEM_C_API ESP_MODEM C API
+ * @brief Set of basic C API for ESP-MODEM
+ */
+/** @addtogroup ESP_MODEM_C_API
+ * @{
+ */
+
+/**
+ * @brief DCE mode: This enum is used to set desired operation mode of the DCE
+ */
 typedef enum esp_modem_dce_mode
 {
-    ESP_MODEM_MODE_COMMAND,
-    ESP_MODEM_MODE_DATA,
+    ESP_MODEM_MODE_COMMAND,  /**< Default mode after modem startup, used for sending AT commands */
+    ESP_MODEM_MODE_DATA,     /**< Used for switching to PPP mode for the modem to connect to a network */
 } esp_modem_dce_mode_t;
 
+/**
+ * @brief Create a DCE handle for new modem API
+ *
+ * @param dte_config DTE configuration (UART config for now)
+ * @param dce_config DCE configuration
+ * @param netif Network interface handle for the data mode
+ *
+ * @return DCE pointer on success, NULL on failure
+ */
 esp_modem_dce_t *esp_modem_new(const esp_modem_dte_config_t *dte_config, const esp_modem_dce_config_t *dce_config, esp_netif_t *netif);
 
+/**
+ * @brief Destroys modem's DCE handle
+ *
+ * @param dce DCE to destroy
+ */
 void esp_modem_destroy(esp_modem_dce_t * dce);
+
+/**
+ * @brief Set operation mode for this DCE
+ * @param dce Modem DCE handle
+ * @param mode Desired MODE
+ * @return ESP_OK on success, ESP_FAIL on failure
+ */
 esp_err_t esp_modem_set_mode(esp_modem_dce_t * dce, esp_modem_dce_mode_t mode);
 
+/**
+ * @}
+ */
 
 #ifdef __cplusplus
 }

esp_modem/include/generate/esp_modem_command_declare.inc

@@ -15,12 +15,18 @@
 #ifndef _ESP_MODEM_COMMAND_DECLARE_INC_
 #define _ESP_MODEM_COMMAND_DECLARE_INC_
 
+#if GENERATE_DOCS
+#define _ARG(arg) arg
+#else
+#define _ARG(arg) x
+#endif
+
 #ifdef __cplusplus
 #include <string>
-#define STRING_IN(x) const std::string& x
-#define STRING_OUT(x) std::string& x
+#define STRING_IN(x) const std::string& _ARG(x)
+#define STRING_OUT(x) std::string& _ARG(x)
 #define BOOL_IN(x) const bool x
-#define BOOL_OUT(x) bool& x
+#define BOOL_OUT(x) bool& _ARG(x)
 #define INT_OUT(x) int& x
 
 #define STRUCT_OUT(struct_name, x)  struct_name& x
@@ -42,36 +48,74 @@
  * @brief Sends the supplied PIN code
  *
  * @param pin Pin
+ *
  */ \
     \
-ESP_MODEM_DECLARE_DCE_COMMAND(set_pin,  command_result, 1, MUX_ARG, STRING_IN(x)) \
+ESP_MODEM_DECLARE_DCE_COMMAND(set_pin,  command_result, 1, MUX_ARG, STRING_IN(pin)) \
+\
+\
 /**
  * @brief Checks if the SIM needs a PIN
  *
  * @param[out] pin_ok Pin
  */ \
-ESP_MODEM_DECLARE_DCE_COMMAND(read_pin, command_result, 1, MUX_ARG, BOOL_OUT(x))           \
+ESP_MODEM_DECLARE_DCE_COMMAND(read_pin, command_result, 1, MUX_ARG, BOOL_OUT(pin_ok))           \
     \
+/**
+ * @brief Reads the module name
+ *
+ * @param[out] name module name
+ */ \
 ESP_MODEM_DECLARE_DCE_COMMAND(set_echo, command_result, 1, MUX_ARG, BOOL_IN(x))           \
     \
+/**
+ * @brief Reads the module name
+ *
+ * @param[out] name module name
+ */ \
 ESP_MODEM_DECLARE_DCE_COMMAND(resume_data_mode, command_result, 0, MUX_ARG)           \
     \
+/**
+ * @brief Reads the module name
+ *
+ * @param[out] name module name
+ */ \
 ESP_MODEM_DECLARE_DCE_COMMAND(set_pdp_context, command_result, 1, MUX_ARG, STRUCT_OUT(PdpContext, x)) \
     \
+/**
+ * @brief Reads the module name
+ *
+ * @param[out] name module name
+ */ \
 ESP_MODEM_DECLARE_DCE_COMMAND(set_command_mode, command_result, 0, MUX_ARG) \
     \
+/**
+ * @brief Reads the module name
+ *
+ * @param[out] name module name
+ */ \
 ESP_MODEM_DECLARE_DCE_COMMAND(set_cmux, command_result, 0, MUX_ARG) \
     \
+/**
+ * @brief Reads the module name
+ *
+ * @param[out] name module name
+ */ \
 ESP_MODEM_DECLARE_DCE_COMMAND(get_imsi, command_result, 1, MUX_ARG, STRING_OUT(x)) \
     \
+/**
+ * @brief Reads the module name
+ *
+ * @param[out] name module name
+ */ \
 ESP_MODEM_DECLARE_DCE_COMMAND(get_imei, command_result, 1, MUX_ARG, STRING_OUT(x)) \
     \
 /**
  * @brief Reads the module name
  *
- * @param[out]  module name
+ * @param[out] name module name
  */ \
-ESP_MODEM_DECLARE_DCE_COMMAND(get_module_name, command_result, 1, MUX_ARG, STRING_OUT(x)) \
+ESP_MODEM_DECLARE_DCE_COMMAND(get_module_name, command_result, 1, MUX_ARG, STRING_OUT(name)) \
 \
 /**
  * @brief Sets the modem to data mode
@@ -85,15 +129,26 @@ ESP_MODEM_DECLARE_DCE_COMMAND(set_data_mode, command_result, 0, MUX_ARG) \
  */ \
 ESP_MODEM_DECLARE_DCE_COMMAND(get_signal_quality, command_result, 2, MUX_ARG, INT_OUT(x), INT_OUT(y))
 
-//  --- DCE command documentation starts here ---
 #ifdef GENERATE_DOCS
-// gcc -E -CC -P -DGENERATE_DOCS esp_modem_command_declare.inc | sed -n '/DCE command documentation/,//p'
-
-#define ESP_MODEM_DECLARE_DCE_COMMAND(name, return_type, TEMPLATE_ARG, MUX_ARG, ...) \
-return_type name (__VA_ARGS__);
-
-DECLARE_ALL_COMMAND_APIS()
+// cat ../include/generate/esp_modem_command_declare.inc | clang++ -E -P -CC  -xc++ -I../include -DGENERATE_DOCS  - | sed -n '1,/DCE command documentation/!p'
+// cat ../include/generate/esp_modem_command_declare.inc | clang -E -P -CC  -xc -I../include -DGENERATE_DOCS  - | sed -n '1,/DCE command documentation/!p' > c_api.h
+//  --- DCE command documentation starts here ---
+#ifdef __cplusplus
+class DCE: public DCE_T<GenericModule> {
+public:
+    using DCE_T<GenericModule>::DCE_T;
+#define ESP_MODEM_DECLARE_DCE_COMMAND(name, return_type, TEMPLATE_ARG, MUX_ARG, ...) return_type name (__VA_ARGS__);
+#else
+#define ESP_MODEM_DECLARE_DCE_COMMAND(name, return_type, TEMPLATE_ARG, MUX_ARG, ...) return_type esp_modem_ ## name (__VA_ARGS__);
 #endif
 
 
+DECLARE_ALL_COMMAND_APIS()
+
+#ifdef __cplusplus
+};
+#endif
+
+#endif
+
 #endif // _ESP_MODEM_COMMAND_DECLARE_INC_