doc: updated comments

WIKI_EN.md

@@ -163,10 +163,10 @@ Initializes the PCF8574 expander.
 **Returns:**
 
 - `ESP_OK` - Success
-- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL config or handle)
+- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL config, handle or *handle)
 - `ESP_ERR_INVALID_STATE` - Expander already initialized
 - `ESP_ERR_NO_MEM` - Insufficient memory
-- `ESP_ERR_NOT_SUPPORTED` - I2C initialization error
+- `ESP_FAIL` - Configuration validation, I2C communication, or task creation error
 
 ---
 
@@ -182,6 +182,8 @@ Deinitializes the PCF8574 expander.
 
 - `ESP_OK` - Success
 - `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle or *handle)
+- `ESP_ERR_NOT_FOUND` - Handle does not correspond to a registered device
+- `ESP_FAIL` - I2C removal or vector operation error
 
 ---
 
@@ -197,10 +199,9 @@ Reads the state of all GPIO pins of the expander.
 **Returns:**
 
 - `ESP_OK` - Success
-- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle or reg)
+- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle, *handle or reg)
-- `ESP_ERR_INVALID_STATE` - Expander not initialized
+- `ESP_ERR_NOT_FOUND` - Handle does not correspond to a registered device
-
+- `ESP_FAIL` - I2C communication or vector operation error
-**Note:** For input GPIOs, the value will always be 1 (HIGH).
 
 ---
 
@@ -216,8 +217,9 @@ Sets the state of all output GPIO pins of the expander.
 **Returns:**
 
 - `ESP_OK` - Success
-- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle)
+- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle or *handle)
-- `ESP_ERR_INVALID_STATE` - Expander not initialized
+- `ESP_ERR_NOT_FOUND` - Handle does not correspond to a registered device
+- `ESP_FAIL` - I2C communication or vector operation error
 
 **Note:** Only output GPIOs are affected.
 
@@ -235,6 +237,8 @@ Resets all GPIO pins of the expander to the initial state.
 
 - `ESP_OK` - Success
 - `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle or *handle)
+- `ESP_ERR_NOT_FOUND` - Handle does not correspond to a registered device
+- `ESP_FAIL` - I2C communication or vector operation error
 
 ---
 
@@ -251,8 +255,8 @@ Reads the state of one GPIO pin of the expander.
 **Returns:**
 
 - `ESP_OK` - Success
-- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle, gpio, status or gpio out of range)
+- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle or status)
-- `ESP_ERR_INVALID_STATE` - Expander not initialized
+- `ESP_FAIL` - Invalid gpio, handle mismatch, or I2C communication error
 
 **Note:** For input GPIOs, the value will always be 1 (HIGH).
 
@@ -271,8 +275,8 @@ Sets the state of one output GPIO pin of the expander.
 **Returns:**
 
 - `ESP_OK` - Success
-- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle, gpio, status or gpio out of range)
+- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle)
-- `ESP_ERR_INVALID_STATE` - Expander not initialized
+- `ESP_FAIL` - Invalid gpio, handle mismatch, or I2C communication error
 
 **Note:** Only output GPIOs are affected.
 
@@ -303,7 +307,7 @@ Resets error statistics counters.
 
 #define I2C_PORT (I2C_NUM_MAX - 1)
 
-zh_pcf8574_handle_t pcf8574_handle = {0};
+zh_pcf8574_handle_t *pcf8574_handle = NULL;
 
 void print_gpio_status(const char *message, uint8_t reg)
 {
@@ -371,7 +375,7 @@ void app_main(void)
 
 #define I2C_PORT (I2C_NUM_MAX - 1)
 
-zh_pcf8574_handle_t pcf8574_handle = {0};
+zh_pcf8574_handle_t *pcf8574_handle = NULL;
 
 void zh_pcf8574_event_handler(void *arg, esp_event_base_t event_base, int32_t event_id, void *event_data)
 {
@@ -441,7 +445,7 @@ void app_main(void)
 | `ESP_OK` | Operation successful |
 | `ESP_ERR_INVALID_ARG` | Invalid argument (NULL pointer or invalid configuration) |
 | `ESP_ERR_INVALID_STATE` | Device not initialized or already initialized |
-| `ESP_ERR_NOT_FOUND` | Device not initialized |
+| `ESP_ERR_NOT_FOUND` | Handle does not correspond to a registered device |
 | `ESP_ERR_NO_MEM` | Insufficient memory |
 | `ESP_FAIL` | General failure (I2C communication error, initialization error, etc.) |
 

WIKI_RU.md

@@ -163,10 +163,10 @@ typedef struct
 **Возвращает:**
 
 - `ESP_OK` - Успех
-- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL config или handle)
+- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL config, handle или *handle)
 - `ESP_ERR_INVALID_STATE` - Расширитель уже инициализирован
 - `ESP_ERR_NO_MEM` - Недостаточно памяти
-- `ESP_ERR_NOT_SUPPORTED` - Ошибка инициализации I2C
+- `ESP_FAIL` - Ошибка валидации конфигурации, I2C-связи или создания задачи
 
 ---
 
@@ -182,6 +182,8 @@ typedef struct
 
 - `ESP_OK` - Успех
 - `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle или *handle)
+- `ESP_ERR_NOT_FOUND` - Handle не соответствует зарегистрированному устройству
+- `ESP_FAIL` - Ошибка удаления I2C или операций с вектором
 
 ---
 
@@ -197,10 +199,9 @@ typedef struct
 **Возвращает:**
 
 - `ESP_OK` - Успех
-- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle или reg)
+- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle, *handle или reg)
-- `ESP_ERR_INVALID_STATE` - Расширитель не инициализирован
+- `ESP_ERR_NOT_FOUND` - Handle не соответствует зарегистрированному устройству
-
+- `ESP_FAIL` - Ошибка I2C-связи или операций с вектором
-**Примечание:** Для входных GPIO всегда будет 1 (HIGH).
 
 ---
 
@@ -216,10 +217,11 @@ typedef struct
 **Возвращает:**
 
 - `ESP_OK` - Успех
-- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle)
+- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle или *handle)
-- `ESP_ERR_INVALID_STATE` - Расширитель не инициализирован
+- `ESP_ERR_NOT_FOUND` - Handle не соответствует зарегистрированному устройству
+- `ESP_FAIL` - Ошибка I2C-связи или операций с вектором
 
-**Примечание:** Влияет только на выходные GPIO.
+**Примечание:** Только на выходные GPIO влияет.
 
 ---
 
@@ -235,6 +237,8 @@ typedef struct
 
 - `ESP_OK` - Успех
 - `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle или *handle)
+- `ESP_ERR_NOT_FOUND` - Handle не соответствует зарегистрированному устройству
+- `ESP_FAIL` - Ошибка I2C-связи или операций с вектором
 
 ---
 
@@ -251,8 +255,8 @@ typedef struct
 **Возвращает:**
 
 - `ESP_OK` - Успех
-- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle, gpio, status или выход gpio за пределы)
+- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle или status)
-- `ESP_ERR_INVALID_STATE` - Расширитель не инициализирован
+- `ESP_FAIL` - Неверный номер gpio, handle не соответствует устройству или I2C-связь
 
 **Примечание:** Для входных GPIO всегда будет 1 (HIGH).
 
@@ -271,8 +275,8 @@ typedef struct
 **Возвращает:**
 
 - `ESP_OK` - Успех
-- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle, gpio, status или выход gpio за пределы)
+- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle)
-- `ESP_ERR_INVALID_STATE` - Расширитель не инициализирован
+- `ESP_FAIL` - Неверный номер gpio, handle не соответствует устройству или I2C-связь
 
 **Примечание:** Влияет только на выходные GPIO.
 
@@ -303,7 +307,7 @@ typedef struct
 
 #define I2C_PORT (I2C_NUM_MAX - 1)
 
-zh_pcf8574_handle_t pcf8574_handle = {0};
+zh_pcf8574_handle_t *pcf8574_handle = NULL;
 
 void print_gpio_status(const char *message, uint8_t reg)
 {
@@ -371,7 +375,7 @@ void app_main(void)
 
 #define I2C_PORT (I2C_NUM_MAX - 1)
 
-zh_pcf8574_handle_t pcf8574_handle = {0};
+zh_pcf8574_handle_t *pcf8574_handle = NULL;
 
 void zh_pcf8574_event_handler(void *arg, esp_event_base_t event_base, int32_t event_id, void *event_data)
 {
@@ -441,7 +445,7 @@ void app_main(void)
 | `ESP_OK` | Операция выполнена успешно |
 | `ESP_ERR_INVALID_ARG` | Неверный аргумент (NULL указатель или неверная конфигурация) |
 | `ESP_ERR_INVALID_STATE` | Устройство не инициализировано или уже инициализировано |
-| `ESP_ERR_NOT_FOUND` | Устройство не инициализировано |
+| `ESP_ERR_NOT_FOUND` | Handle не соответствует зарегистрированному устройству |
 | `ESP_ERR_NO_MEM` | Недостаточно памяти |
 | `ESP_FAIL` | Общая ошибка (ошибка связи I2C, инициализации и т.д.) |
 

include/zh_pcf8574.h

@@ -155,62 +155,72 @@ extern "C"
      * @param[out] handle Pointer to receive the device handle (must be NULL)
      *
      * @return ESP_OK on success
-     * @return ESP_ERR_INVALID_ARG if config parameter is NULL
+     * @return ESP_ERR_INVALID_ARG if config is NULL or handle points to non-NULL
+     * @return ESP_ERR_INVALID_STATE if device is already initialized
      * @return ESP_ERR_NO_MEM if memory allocation fails
-     * @return ESP_ERR_NOT_SUPPORTED if I2C initialization fails
+     * @return ESP_FAIL if configuration validation, I2C communication, or task creation fails
      */
     esp_err_t zh_pcf8574_init(const zh_pcf8574_init_config_t *config, zh_pcf8574_handle_t **handle);
 
     /**
      * @brief Deinitialize PCF8574 device.
      *
-     * Deletes the internal task and releases all allocated resources.
+     * Releases I2C resources and the device handle. Deletes the internal
+     * task only when the last device instance is deinitialized.
      *
-     * @param[in,out] handle Pointer to the device handle (must not be NULL)
+     * @param[in] handle Pointer to the device handle (must not be NULL)
      *
      * @return ESP_OK on success
-     * @return ESP_ERR_INVALID_ARG if handle parameter is NULL
+     * @return ESP_ERR_INVALID_ARG if handle is NULL
+     * @return ESP_ERR_NOT_FOUND if handle does not correspond to a valid device instance
+     * @return ESP_FAIL if I2C removal or vector operations fail
      */
     esp_err_t zh_pcf8574_deinit(zh_pcf8574_handle_t **handle);
 
     /**
      * @brief Read data from PCF8574 device.
      *
-     * Reads a byte from the PCF8574 input ports via I2C communication.
+     * Reads a byte from the PCF8574 input ports via I2C communication
+     * and updates the internal device state.
      *
-     * @param[in,out] handle Pointer to the device handle (must not be NULL)
+     * @param[in] handle Pointer to the device handle (must not be NULL)
      * @param[out] reg Pointer to receive the read value (must not be NULL)
      *
      * @return ESP_OK on success
      * @return ESP_ERR_INVALID_ARG if handle or reg is NULL
-     * @return ESP_ERR_INVALID_STATE if device is not initialized
+     * @return ESP_ERR_NOT_FOUND if handle does not correspond to a valid device instance
+     * @return ESP_FAIL if I2C communication or vector operations fail
      */
     esp_err_t zh_pcf8574_read(zh_pcf8574_handle_t **handle, uint8_t *reg);
 
     /**
      * @brief Write data to PCF8574 device.
      *
-     * Writes a byte to the PCF8574 output ports via I2C communication.
+     * Writes a byte to the PCF8574 output ports via I2C communication
+     * and updates the internal device state.
      *
-     * @param[in,out] handle Pointer to the device handle (must not be NULL)
+     * @param[in] handle Pointer to the device handle (must not be NULL)
      * @param[in] reg Value to write to the output ports
      *
      * @return ESP_OK on success
      * @return ESP_ERR_INVALID_ARG if handle is NULL
-     * @return ESP_ERR_INVALID_STATE if device is not initialized
+     * @return ESP_ERR_NOT_FOUND if handle does not correspond to a valid device instance
+     * @return ESP_FAIL if I2C communication or vector operations fail
      */
     esp_err_t zh_pcf8574_write(zh_pcf8574_handle_t **handle, uint8_t reg);
 
     /**
      * @brief Reset PCF8574 device.
      *
-     * Resets the device to its default state, clearing all outputs
+     * Resets all outputs to their default input configuration
-     * and reinitializing internal structures.
+     * and updates the internal device state.
      *
-     * @param[in,out] handle Pointer to the device handle (must not be NULL)
+     * @param[in] handle Pointer to the device handle (must not be NULL)
      *
      * @return ESP_OK on success
      * @return ESP_ERR_INVALID_ARG if handle is NULL
+     * @return ESP_ERR_NOT_FOUND if handle does not correspond to a valid device instance
+     * @return ESP_FAIL if I2C communication or vector operations fail
      */
     esp_err_t zh_pcf8574_reset(zh_pcf8574_handle_t **handle);
 
@@ -219,13 +229,13 @@ extern "C"
      *
      * Reads the current logical level of a specified GPIO pin.
      *
-     * @param[in,out] handle Pointer to the device handle (must not be NULL)
+     * @param[in] handle Pointer to the device handle (must not be NULL)
      * @param[in] gpio GPIO pin number to read
      * @param[out] status Pointer to receive the pin state (true = high, false = low)
      *
      * @return ESP_OK on success
-     * @return ESP_ERR_INVALID_ARG if handle, gpio, or status is NULL
+     * @return ESP_ERR_INVALID_ARG if handle or status is NULL
-     * @return ESP_ERR_INVALID_ARG if gpio number exceeds ZH_PCF8574_GPIO_NUM_MAX
+     * @return ESP_FAIL if gpio is invalid, handle is invalid, or I2C communication fails
      */
     esp_err_t zh_pcf8574_read_gpio(zh_pcf8574_handle_t **handle, zh_pcf8574_gpio_num_t gpio, bool *status);
 
@@ -234,13 +244,13 @@ extern "C"
      *
      * Sets the logical level of a specified GPIO pin configured as output.
      *
-     * @param[in,out] handle Pointer to the device handle (must not be NULL)
+     * @param[in] handle Pointer to the device handle (must not be NULL)
      * @param[in] gpio GPIO pin number to write
      * @param[in] status Logical level to set (true = high, false = low)
      *
      * @return ESP_OK on success
-     * @return ESP_ERR_INVALID_ARG if handle, gpio, or status is NULL
+     * @return ESP_ERR_INVALID_ARG if handle is NULL
-     * @return ESP_ERR_INVALID_ARG if gpio number exceeds ZH_PCF8574_GPIO_NUM_MAX
+     * @return ESP_FAIL if gpio is invalid, handle is invalid, or I2C communication fails
      */
     esp_err_t zh_pcf8574_write_gpio(zh_pcf8574_handle_t **handle, zh_pcf8574_gpio_num_t gpio, bool status);