MCPWM API Documentation Issue (IDFGH-11443)

[blakecole]

Answers checklist.

• I have read the documentation ESP-IDF Programming Guide and the issue is not addressed there.
• I have updated my IDF branch (master or release) to the latest version and checked that the issue is present there.
• I have searched the issue tracker for a similar issue and not found a similar issue.

General issue report

The description of the structure mcpwm_capture_channel_config_t is incomplete.

Inspection of the mcpwm_cap.h header file reveals that 7 of these member variables are actually contained within a sub-structure called "flags". I will paste the relevant code (lines 134-149) below:

typedef struct {

    int gpio_num;                    /*!< GPIO used capturing input signal */

    int intr_priority;               /*!< MCPWM capture interrupt priority,
                                          if set to 0, the driver will try to allocate an interrupt with a relative low priority (1,2,3) */
    uint32_t prescale;               /*!< Prescale of input signal, effective frequency = cap_input_clk/prescale */

    struct {
        uint32_t pos_edge: 1;          /*!< Whether to capture on positive edge */
        uint32_t neg_edge: 1;          /*!< Whether to capture on negative edge */
        uint32_t pull_up: 1;           /*!< Whether to pull up internally */
        uint32_t pull_down: 1;         /*!< Whether to pull down internally */
        uint32_t invert_cap_signal: 1; /*!< Invert the input capture signal */
        uint32_t io_loop_back: 1;      /*!< For debug/test, the signal output from the GPIO will be fed to the input path as well */
        uint32_t keep_io_conf_at_exit: 1; /*!< For debug/test, whether to keep the GPIO configuration when capture channel is deleted.

                                            By default, driver will reset the GPIO pin at exit. */
    } flags;                           /*!< Extra configuration flags for capture channel */

} mcpwm_capture_channel_config_t;

Further, the link in the documentation assigned to the flags structure is broken, and simply leads circularly back to the top of the struct mcpwm_capture_channel_config_t section.

Of course, if you try to assign values to these 7 members, without the "flags." prefix, you will get errors (which I learned the hard way!)