ledc: explain the callback return value

Closes https://github.com/espressif/esp-idf/issues/10093

components/driver/include/driver/ledc.h

@@ -78,8 +78,9 @@ typedef struct {
  * @brief Type of LEDC event callback
  * @param param LEDC callback parameter
  * @param user_arg User registered data
+ * @return Whether a high priority task has been waken up by this function
  */
-typedef bool (* ledc_cb_t)(const ledc_cb_param_t *param, void *user_arg);
+typedef bool (*ledc_cb_t)(const ledc_cb_param_t *param, void *user_arg);
 
 /**
  * @brief Group of supported LEDC callbacks
@@ -99,7 +100,7 @@ typedef struct {
  *     - ESP_OK Success
  *     - ESP_ERR_INVALID_ARG Parameter error
  */
-esp_err_t ledc_channel_config(const ledc_channel_config_t* ledc_conf);
+esp_err_t ledc_channel_config(const ledc_channel_config_t *ledc_conf);
 
 /**
  * @brief LEDC timer configuration
@@ -112,7 +113,7 @@ esp_err_t ledc_channel_config(const ledc_channel_config_t* ledc_conf);
  *     - ESP_ERR_INVALID_ARG Parameter error
  *     - ESP_FAIL Can not find a proper pre-divider number base on the given frequency and the current duty_resolution.
  */
-esp_err_t ledc_timer_config(const ledc_timer_config_t* timer_conf);
+esp_err_t ledc_timer_config(const ledc_timer_config_t *timer_conf);
 
 /**
  * @brief LEDC update channel parameters
@@ -285,7 +286,7 @@ esp_err_t ledc_set_fade(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t
  *     - ESP_OK Success
  *     - ESP_ERR_INVALID_ARG Function pointer error.
  */
-esp_err_t ledc_isr_register(void (*fn)(void*), void * arg, int intr_alloc_flags, ledc_isr_handle_t *handle);
+esp_err_t ledc_isr_register(void (*fn)(void *), void *arg, int intr_alloc_flags, ledc_isr_handle_t *handle);
 
 /**
  * @brief Configure LEDC settings
@@ -496,6 +497,7 @@ esp_err_t ledc_set_fade_step_and_start(ledc_mode_t speed_mode, ledc_channel_t ch
  *     - ESP_FAIL Fade function init error
  */
 esp_err_t ledc_cb_register(ledc_mode_t speed_mode, ledc_channel_t channel, ledc_cbs_t *cbs, void *user_arg);
+
 #ifdef __cplusplus
 }
 #endif

docs/en/api-reference/peripherals/ledc.rst

@@ -45,7 +45,7 @@ As an optional step, it is also possible to set up an interrupt on fade end.
 
 .. _ledc-api-configure-timer:
 
-Timer Configuration 
+Timer Configuration
 ^^^^^^^^^^^^^^^^^^^
 
 Setting the timer is done by calling the function :cpp:func:`ledc_timer_config` and passing the data structure :cpp:type:`ledc_timer_config_t` that contains the following configuration settings:
@@ -108,7 +108,9 @@ The LEDC hardware provides the means to gradually transition from one duty cycle
 * :cpp:func:`ledc_set_fade_with_step`
 * :cpp:func:`ledc_set_fade`
 
-Finally start fading with :cpp:func:`ledc_fade_start`.
+Start fading with :cpp:func:`ledc_fade_start`. A fade can be operated in blocking or non-blocking mode, please check :cpp:enum:`ledc_fade_mode_t` for the difference between the two available fade modes. Note that with either fade mode, the next fade or fixed-duty update will not take effect until the last fade finishes.
+
+To get a notification about the completion of a fade operation, a fade end callback function can be registered for each channel by calling :cpp:func:`ledc_cb_register` after the fade service being installed. The fade end callback prototype is defined in :cpp:type:`ledc_cb_t`, where you should return a boolean value from the callback function, indicating whether a high priority task is woken up by this callback function.
 
 If not required anymore, fading and an associated interrupt can be disabled with :cpp:func:`ledc_fade_func_uninstall`.
 
@@ -149,11 +151,11 @@ For registration of a handler to address this interrupt, call :cpp:func:`ledc_is
 .. only:: esp32
 
     .. _ledc-api-high_low_speed_mode:
-    
+
     LEDC High and Low Speed Mode
     ----------------------------
 
-    High speed mode enables a glitch-free changeover of timer settings. This means that if the timer settings are modified, the changes will be applied automatically on the next overflow interrupt of the timer. In contrast, when updating the low-speed timer, the change of settings should be explicitly triggered by software. The LEDC driver handles it in the background, e.g., when :cpp:func:`ledc_timer_config` or :cpp:func:`ledc_timer_set` is called. 
+    High speed mode enables a glitch-free changeover of timer settings. This means that if the timer settings are modified, the changes will be applied automatically on the next overflow interrupt of the timer. In contrast, when updating the low-speed timer, the change of settings should be explicitly triggered by software. The LEDC driver handles it in the background, e.g., when :cpp:func:`ledc_timer_config` or :cpp:func:`ledc_timer_set` is called.
 
     For additional details regarding speed modes, see *{IDF_TARGET_NAME} Technical Reference Manual* > *LED PWM Controller (LEDC)* [`PDF <{IDF_TARGET_TRM_EN_URL}#ledpwm>`__]. Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver.
 

docs/zh_CN/api-reference/peripherals/ledc.rst

@@ -108,7 +108,9 @@ LED PWM 控制器硬件可逐渐改变占空比的数值。要使用此功能，
 * :cpp:func:`ledc_set_fade_with_step`
 * :cpp:func:`ledc_set_fade`
 
-最后用 :cpp:func:`ledc_fade_start` 开启渐变。
+最后需要调用 :cpp:func:`ledc_fade_start` 开启渐变。渐变可以在阻塞或非阻塞模式下运行，具体区别请查看 :cpp:enum:`ledc_fade_mode_t`。需要特别注意的是，不管在哪种模式下，下一次渐变或单次占空比配置的指令生效都必须等到前一次渐变结束。
+
+此外，在使能渐变后，每个通道都可以额外通过调用 :cpp:func:`ledc_cb_register` 注册一个回调函数用以获得渐变完成的事件通知。回调函数的原型被定义在 :cpp:type:`ledc_cb_t`。每个回调函数都应当返回一个布尔值给驱动的中断处理函数，用以表示是否有高优先级任务被其唤醒。
 
 如不需要渐变和渐变中断，可用函数 :cpp:func:`ledc_fade_func_uninstall` 关闭。