fix(modem): Fixup the docs

Author: david-cermak

.github/workflows/modem__build-host-tests.yml

@@ -108,11 +108,13 @@ jobs:
     steps:
       - name: Checkout esp-protocols
         uses: actions/checkout@v4
+      - name: Compat check
         shell: bash
         run: |
-          apt-get update -y
-          apt-get install -y astyle
+          sudo apt-get update -y
+          sudo apt-get install -y astyle
           cd components/esp_modem
           find examples/ -type f -regex '.*/generate/.*\.\(hpp\|cpp\)' -exec ./scripts/generate.sh {} \;
           ./scripts/generate.sh
+          git diff --name-only
           git diff --quiet

components/esp_modem/command/include/cxx_include/esp_modem_command_library.hpp

@@ -10,18 +10,15 @@
 #include "cxx_include/esp_modem_dce_module.hpp"
 #include "cxx_include/esp_modem_types.hpp"
 
-//  --- ESP-MODEM command module starts here ---
 namespace esp_modem {
 namespace dce_commands {
-
 /**
  * @defgroup ESP_MODEM_DCE_COMMAND ESP_MODEM DCE command library
  * @brief Library of the most useful DCE commands
  */
 /** @addtogroup ESP_MODEM_DCE_COMMAND
  * @{
  */
-
 /**
  * @brief Generic AT command to be send with pass and fail phrases
  *
@@ -34,72 +31,32 @@ namespace dce_commands {
 command_result generic_command(CommandableIf *t, const std::string &command,
                                const std::string &pass_phrase,
                                const std::string &fail_phrase, uint32_t timeout_ms);
-
 /**
  * @brief Declaration of all commands is generated from esp_modem_command_declare.inc
  */
-
-
-//
-//#define INT_IN(name) int name
-//#ifdef __cplusplus
-//#define STRING_IN(name) const std::string& name
-//#define STRING_OUT(name) std::string& name
-//#define BOOL_IN(name) const bool name
-//#define BOOL_OUT(name) bool& name
-//#define INT_OUT(name) int& name
-//#define INTEGER_LIST_IN(name) const int* name
-//#define STRUCT_OUT(struct_name, name)  struct_name& name
-//#else
-//#define STRING_IN(name) const char* name
-//#define STRING_OUT(name) char* name
-//#define BOOL_IN(name) const bool name
-//#define BOOL_OUT(name) bool* name
-//#define INT_OUT(name) int* name
-//#define INTEGER_LIST_IN(name) const int* name
-//#define STRUCT_OUT(struct_name, name)  esp_modem_ ## struct_name ## _t* name
-//#endif
-//
-//#define FORWARD_INT_IN(name) name
-//#define FORWARD_STRING_IN(name) name
-//#define FORWARD_STRING_OUT(name) name
-//#define FORWARD_BOOL_IN(name) name
-//#define FORWARD_BOOL_OUT(name) name
-//#define FORWARD_INT_OUT(name) name
-//#define FORWARD_INTEGER_LIST_IN(name) name
-//#define FORWARD_STRUCT_OUT(struct_name, name) name
-
-// Utility to count arguments (works for up to two parameters here)
-
-
-
 /**
  * @brief Sends the initial AT sequence to sync up with the device
  * @return OK, FAIL or TIMEOUT
  */
 command_result sync(CommandableIf *t );
-
 /**
  * @brief Reads the operator name
  * @param[out] name operator name
  * @param[out] act access technology
  * @return OK, FAIL or TIMEOUT
  */
 command_result get_operator_name(CommandableIf *t, std::string &name, int &act );
-
 /**
  * @brief Stores current user profile
  * @return OK, FAIL or TIMEOUT
  */
 command_result store_profile(CommandableIf *t );
-
 /**
  * @brief Sets the supplied PIN code
  * @param[in] pin Pin
  * @return OK, FAIL or TIMEOUT
  */
 command_result set_pin(CommandableIf *t, const std::string &pin );
-
 /**
  * @brief Execute the supplied AT command in raw mode (doesn't append '\r' to command, returns everything)
  * @param[in] cmd String command that's send to DTE
@@ -110,7 +67,6 @@ command_result set_pin(CommandableIf *t, const std::string &pin );
  * @return OK, FAIL or TIMEOUT
  */
 command_result at_raw(CommandableIf *t, const std::string &cmd, std::string &out, const std::string &pass, const std::string &fail, int timeout );
-
 /**
  * @brief Execute the supplied AT command
  * @param[in] cmd AT command
@@ -119,116 +75,99 @@ command_result at_raw(CommandableIf *t, const std::string &cmd, std::string &out
  * @return OK, FAIL or TIMEOUT
  */
 command_result at(CommandableIf *t, const std::string &cmd, std::string &out, int timeout );
-
 /**
  * @brief Checks if the SIM needs a PIN
  * @param[out] pin_ok true if the SIM card doesn't need a PIN to unlock
  * @return OK, FAIL or TIMEOUT
  */
 command_result read_pin(CommandableIf *t, bool &pin_ok );
-
 /**
  * @brief Sets echo mode
  * @param[in] echo_on true if echo mode on (repeats the commands)
  * @return OK, FAIL or TIMEOUT
  */
 command_result set_echo(CommandableIf *t, const bool echo_on );
-
 /**
  * @brief Sets the Txt or Pdu mode for SMS (only txt is supported)
  * @param[in] txt true if txt mode
  * @return OK, FAIL or TIMEOUT
  */
 command_result sms_txt_mode(CommandableIf *t, const bool txt );
-
 /**
  * @brief Sets the default (GSM) character set
  * @return OK, FAIL or TIMEOUT
  */
 command_result sms_character_set(CommandableIf *t );
-
 /**
  * @brief Sends SMS message in txt mode
  * @param[in] number Phone number to send the message to
  * @param[in] message Text message to be sent
  * @return OK, FAIL or TIMEOUT
  */
 command_result send_sms(CommandableIf *t, const std::string &number, const std::string &message );
-
 /**
  * @brief Resumes data mode (Switches back to the data mode, which was temporarily suspended)
  * @return OK, FAIL or TIMEOUT
  */
 command_result resume_data_mode(CommandableIf *t );
-
 /**
  * @brief Sets php context
  * @param[in] p1 PdP context struct to setup modem cellular connection
  * @return OK, FAIL or TIMEOUT
  */
 command_result set_pdp_context(CommandableIf *t, PdpContext &pdp );
-
 /**
  * @brief Switches to the command mode
  * @return OK, FAIL or TIMEOUT
  */
 command_result set_command_mode(CommandableIf *t );
-
 /**
  * @brief Switches to the CMUX mode
  * @return OK, FAIL or TIMEOUT
  */
 command_result set_cmux(CommandableIf *t );
-
 /**
  * @brief Reads the IMSI number
  * @param[out] imsi Module's IMSI number
  * @return OK, FAIL or TIMEOUT
  */
 command_result get_imsi(CommandableIf *t, std::string &imsi );
-
 /**
  * @brief Reads the IMEI number
  * @param[out] imei Module's IMEI number
  * @return OK, FAIL or TIMEOUT
  */
 command_result get_imei(CommandableIf *t, std::string &imei );
-
 /**
  * @brief Reads the module name
  * @param[out] name module name
  * @return OK, FAIL or TIMEOUT
  */
 command_result get_module_name(CommandableIf *t, std::string &name );
-
 /**
  * @brief Sets the modem to data mode
  * @return OK, FAIL or TIMEOUT
  */
 command_result set_data_mode(CommandableIf *t );
-
 /**
  * @brief Get Signal quality
  * @param[out] rssi signal strength indication
  * @param[out] ber channel bit error rate
  * @return OK, FAIL or TIMEOUT
  */
 command_result get_signal_quality(CommandableIf *t, int &rssi, int &ber );
-
 /**
  * @brief Sets HW control flow
  * @param[in] dce_flow 0=none, 2=RTS hw flow control of DCE
  * @param[in] dte_flow 0=none, 2=CTS hw flow control of DTE
  * @return OK, FAIL or TIMEOUT
  */
 command_result set_flow_control(CommandableIf *t, int dce_flow, int dte_flow );
-
 /**
  * @brief Hangs up current data call
  * @return OK, FAIL or TIMEOUT
  */
 command_result hang_up(CommandableIf *t );
-
 /**
  * @brief Get voltage levels of modem power up circuitry
  * @param[out] voltage Current status in mV
@@ -237,26 +176,22 @@ command_result hang_up(CommandableIf *t );
  * @return OK, FAIL or TIMEOUT
  */
 command_result get_battery_status(CommandableIf *t, int &voltage, int &bcs, int &bcl );
-
 /**
  * @brief Power down the module
  * @return OK, FAIL or TIMEOUT
  */
 command_result power_down(CommandableIf *t );
-
 /**
  * @brief Reset the module
  * @return OK, FAIL or TIMEOUT
  */
 command_result reset(CommandableIf *t );
-
 /**
  * @brief Configures the baudrate
  * @param[in] baud Desired baud rate of the DTE
  * @return OK, FAIL or TIMEOUT
  */
 command_result set_baud(CommandableIf *t, int baud );
-
 /**
  * @brief Force an attempt to connect to a specific operator
  * @param[in] mode mode of attempt
@@ -273,49 +208,42 @@ command_result set_baud(CommandableIf *t, int baud );
  * @return OK, FAIL or TIMEOUT
  */
 command_result set_operator(CommandableIf *t, int mode, int format, const std::string &oper );
-
 /**
  * @brief Attach or detach from the GPRS service
  * @param[in] state 1-attach 0-detach
  * @return OK, FAIL or TIMEOUT
  */
 command_result set_network_attachment_state(CommandableIf *t, int state );
-
 /**
  * @brief Get network attachment state
  * @param[out] state 1-attached 0-detached
  * @return OK, FAIL or TIMEOUT
  */
 command_result get_network_attachment_state(CommandableIf *t, int &state );
-
 /**
  * @brief What mode the radio should be set to
  * @param[in] state state 1-full 0-minimum ...
  * @return OK, FAIL or TIMEOUT
  */
 command_result set_radio_state(CommandableIf *t, int state );
-
 /**
  * @brief Get current radio state
  * @param[out] state 1-full 0-minimum ...
  * @return OK, FAIL or TIMEOUT
  */
 command_result get_radio_state(CommandableIf *t, int &state );
-
 /**
  * @brief Set network mode
  * @param[in] mode preferred mode
  * @return OK, FAIL or TIMEOUT
  */
 command_result set_network_mode(CommandableIf *t, int mode );
-
 /**
  * @brief Preferred network mode (CAT-M and/or NB-IoT)
  * @param[in] mode preferred selection
  * @return OK, FAIL or TIMEOUT
  */
 command_result set_preferred_mode(CommandableIf *t, int mode );
-
 /**
  * @brief Set network bands for CAT-M or NB-IoT
  * @param[in] mode CAT-M or NB-IoT
@@ -324,30 +252,24 @@ command_result set_preferred_mode(CommandableIf *t, int mode );
  * @return OK, FAIL or TIMEOUT
  */
 command_result set_network_bands(CommandableIf *t, const std::string &mode, const int *bands, int size );
-
 /**
  * @brief Show network system mode
  * @param[out] mode current network mode
  * @return OK, FAIL or TIMEOUT
  */
 command_result get_network_system_mode(CommandableIf *t, int &mode );
-
 /**
  * @brief GNSS power control
  * @param[out] mode power mode (0 - off, 1 - on)
  * @return OK, FAIL or TIMEOUT
  */
 command_result set_gnss_power_mode(CommandableIf *t, int mode );
-
 /**
  * @brief GNSS power control
  * @param[out] mode power mode (0 - off, 1 - on)
  * @return OK, FAIL or TIMEOUT
  */
 command_result get_gnss_power_mode(CommandableIf *t, int &mode );
-
-
-
 /**
  * @brief Following commands that are different for some specific modules
  */
@@ -359,10 +281,8 @@ command_result set_network_bands_sim76xx(CommandableIf *t, const std::string &mo
 command_result power_down_sim8xx(CommandableIf *t);
 command_result set_data_mode_alt(CommandableIf *t);
 command_result set_pdp_context(CommandableIf *t, PdpContext &pdp, uint32_t timeout_ms);
-
 /**
  * @}
  */
-
 } // dce_commands
 } // esp_modem