When is tools/gen_esp_err_to_name.py used?

[atx823]

Under esp_err_to_name_r the esp-idf docs say: "The function is generated by the Python script tools/gen_esp_err_to_name.py which should be run each time an esp_err_t error is modified, created or removed from the IDF project."

What exactly does it mean to add, modify, create or remove an esp_err_t error?

Is there an example of when this might be done?

[ESP_Sprite]

Say you have your own component that needs to be able to generate a very specific error... say you have a device driver that needs to indicate that a device overheated and can't respond because of that, and you feel that you cannot map that to an existing error value as the overheating problem is something you want to have the rest of your code specifically know about or log. You could do that by defining an error for that component, say ESP_ERR_OVERHEATED. You can define that in a public header in your component. Issue is that esp_err_to_str() and related functions can't automatically see you defined a new error, so if you do an ESP_ERROR_CHECK(some_call(my_device)) and it returns ESP_ERR_OVERHEATED, you'll only see the numeric value. If you re-run the gen_esp_err_to_name.py script, however, it'll pick up that error value and make the system know about it, so you will see the string.

Sorry, not the clearest explanation in the world, hope it's understandable.

[atx823]

So just to confirm, gen_esp_err_to_name.py will search through all the header files of my components, and extract defines of symbols starting with "ESP_ERR_".

Thanks very much.