docs(ledc): Document LEDC functions in header file

Author: P-R-O-C-H-Y

cores/esp32/esp32-hal-ledc.h

@@ -45,20 +45,150 @@ typedef struct {
 #endif
 } ledc_channel_handle_t;
 
-bool        ledcAttach(uint8_t pin, uint32_t freq, uint8_t resolution);
-bool        ledcAttachChannel(uint8_t pin, uint32_t freq, uint8_t resolution, uint8_t channel);
-bool        ledcWrite(uint8_t pin, uint32_t duty);
-uint32_t    ledcWriteTone(uint8_t pin, uint32_t freq);
-uint32_t    ledcWriteNote(uint8_t pin, note_t note, uint8_t octave);
-uint32_t    ledcRead(uint8_t pin);
-uint32_t    ledcReadFreq(uint8_t pin);
-bool        ledcDetach(uint8_t pin);
-uint32_t    ledcChangeFrequency(uint8_t pin, uint32_t freq, uint8_t resolution);
-bool        ledcOutputInvert(uint8_t pin, bool out_invert);
+/**
+ * @brief Attach a pin to the LEDC driver, with a given frequency and resolution.
+ *        Channel is automatically assigned.
+ *
+ * @param pin GPIO pin
+ * @param freq frequency of PWM signal
+ * @param resolution resolution for LEDC pin
+ *
+ * @return true if configuration is successful and pin was successfully attached, false otherwise.
+ */
+bool ledcAttach(uint8_t pin, uint32_t freq, uint8_t resolution);
+
+/**
+ * @brief Attach a pin to the LEDC driver, with a given frequency, resolution and channel.
+ *
+ * @param pin GPIO pin
+ * @param freq frequency of PWM signal
+ * @param resolution resolution for LEDC pin
+ * @param channel LEDC channel to attach to
+ *
+ * @return true if configuration is successful and pin was successfully attached, false otherwise.
+ */
+bool ledcAttachChannel(uint8_t pin, uint32_t freq, uint8_t resolution, uint8_t channel);
+
+/**
+ * @brief Set the duty cycle of a given pin.
+ *
+ * @param pin GPIO pin
+ * @param duty duty cycle to set
+ *
+ * @return true if duty cycle was successfully set, false otherwise.
+ */
+bool ledcWrite(uint8_t pin, uint32_t duty);
+
+/**
+ * @brief Sets the duty to 50 % PWM tone on selected frequency.
+ *
+ * @param pin GPIO pin
+ * @param freq select frequency of pwm signal. If frequency is 0, duty will be set to 0.
+ *
+ * @return frequency if tone was successfully set.
+ *         If ``0`` is returned, error occurs and LEDC pin was not configured.
+ */
+uint32_t ledcWriteTone(uint8_t pin, uint32_t freq);
+
+/**
+ * @brief Sets the LEDC pin to specific note.
+ *
+ * @param pin GPIO pin
+ * @param note select note to be set (NOTE_C, NOTE_Cs, NOTE_D, NOTE_Eb, NOTE_E, NOTE_F, NOTE_Fs, NOTE_G, NOTE_Gs, NOTE_A, NOTE_Bb, NOTE_B).
+ * @param octave select octave for note.
+ *
+ * @return frequency if note was successfully set.
+ *         If ``0`` is returned, error occurs and LEDC pin was not configured.
+ */
+uint32_t ledcWriteNote(uint8_t pin, note_t note, uint8_t octave);
+
+/**
+ * @brief Read the duty cycle of a given LEDC pin.
+ *
+ * @param pin GPIO pin
+ *
+ * @return duty cycle of selected LEDC pin.
+ */
+uint32_t ledcRead(uint8_t pin);
+
+/**
+ * @brief Read the frequency of a given LEDC pin.
+ *
+ * @param pin GPIO pin
+ *
+ * @return frequency of selected LEDC pin.
+ */
+uint32_t ledcReadFreq(uint8_t pin);
+
+/**
+ * @brief Detach a pin from the LEDC driver.
+ *
+ * @param pin GPIO pin
+ *
+ * @return true if pin was successfully detached, false otherwise.
+ */
+bool ledcDetach(uint8_t pin);
+
+/**
+ * @brief Change the frequency and resolution of a given LEDC pin.
+ * 
+ * @param pin GPIO pin
+ * @param freq frequency of PWM signal
+ * @param resolution resolution for LEDC pin
+ * 
+ * @return frequency configured for the LEDC channel.
+ *         If ``0`` is returned, error occurs and LEDC pin was not configured.
+ */
+uint32_t ledcChangeFrequency(uint8_t pin, uint32_t freq, uint8_t resolution);
+
+/**
+ * @brief Sets inverting of the output signal for a given LEDC pin.
+ * 
+ * @param pin GPIO pin
+ * @param out_invert select, if output should be inverted (1 = inverting output).
+ * 
+ * @return true if output inverting was successfully set, false otherwise.
+ */
+bool ledcOutputInvert(uint8_t pin, bool out_invert);
 
 //Fade functions
+/**
+ * @brief Setup and start a fade on a given LEDC pin.
+ * 
+ * @param pin GPIO pin
+ * @param start_duty initial duty cycle of the fade
+ * @param target_duty target duty cycle of the fade
+ * @param max_fade_time_ms maximum fade time in milliseconds
+ * 
+ * @return true if fade was successfully set and started, false otherwise.
+ */
 bool ledcFade(uint8_t pin, uint32_t start_duty, uint32_t target_duty, int max_fade_time_ms);
+
+/**
+ * @brief Setup and start a fade on a given LEDC pin with a callback function.
+ * 
+ * @param pin GPIO pin
+ * @param start_duty initial duty cycle of the fade
+ * @param target_duty target duty cycle of the fade
+ * @param max_fade_time_ms maximum fade time in milliseconds
+ * @param userFunc callback function to be called after fade is finished
+ * 
+ * @return true if fade was successfully set and started, false otherwise.
+ */
 bool ledcFadeWithInterrupt(uint8_t pin, uint32_t start_duty, uint32_t target_duty, int max_fade_time_ms, void (*userFunc)(void));
+
+/**
+ * @brief Setup and start a fade on a given LEDC pin with a callback function and argument.
+ * 
+ * @param pin GPIO pin
+ * @param start_duty initial duty cycle of the fade
+ * @param target_duty target duty cycle of the fade
+ * @param max_fade_time_ms maximum fade time in milliseconds
+ * @param userFunc callback function to be called after fade is finished
+ * @param arg argument to be passed to the callback function
+ * 
+ * @return true if fade was successfully set and started, false otherwise.
+ */
 bool ledcFadeWithInterruptArg(uint8_t pin, uint32_t start_duty, uint32_t target_duty, int max_fade_time_ms, void (*userFunc)(void*), void * arg);
 
 #ifdef __cplusplus