AI Generation of API Documentation

[Xylopyrographer]

@me-no-dev @pedrominatel

The arduino-esp32 project exists to increase revenue to Espressif by providing an access pathway simpler than their native ESP-IDF IDE thereby increasing utilization and purchase of their ESP32 series of SoC's.

The teams behind this project have and continue to do outstanding work to reduce the complexity of extremely large set of functions, configurations, and build options when developing software for the ESP32 family by making the arduino-esp32 framework available and they are to be commended for their efforts.

In my personal experience, a barrier exists in adoption of the framework as the ESP32 family far exceeds the capabilities of the processors used by Arduino. Utilization of these features requires additions and deviations from and to the API's published and maintained by Arduino. These differences require documentation which unfortunately is not always published or maintained.

While an oft-repeated response would be "It's in the .h files." this is contrary to the point of the framework and the project to provide an easy access entry point to the ESP32 family as you have to know how and where to find a specific header file and as well this does not inform the user of things such as sequencing of initialization, order of calls and such.

The above is preamble to the question: With the plethora of AI tools available, why would the core release workflow not include a process where API documentation is generated and updated with those tools concurrent with the release?

As a quick example, the file below was generated by ChatGPT against the HardwareSerial.h file for core version 3.2.1.

How hard would it be to, eventually, incorporate this across the entire core?

Let's have a conversation.

HardwareSerial API Documentation.md

HardwareSerial API Documentation_rst.txt

(Note, need to change the extension of the attached ".txt" file to be just ".rst"

[me-no-dev]

Honestly I've been waiting for the APIs to mature, the AIs to mature and know of the APIs and to be able to have a better vision of the code. I did try this a few times in the past and the results were not good. Either the wrong APIs were documented or output was very partial. I guess it's time to give it another shot

[Xylopyrographer]

For sure worth another shot.

Attaching two other examples. The doc for ETH was created using ChatGPT.

The API doc for the Peripheral Manager was created using Claude.

It's be worth a review to check the accuracy. 😄

Prompt for Claude was:

Can you create a complete API document for the code from these URL's:
https://github.com/espressif/arduino-esp32/blob/master/cores/esp32/esp32-hal-periman.c
https://github.com/espressif/arduino-esp32/blob/master/cores/esp32/esp32-hal-periman.h

Any other required information should be available from this base URL: https://github.com/espressif/arduino-esp32/tree/master/cores/esp32

The API documentation should include:
* All public classes, structs, enums, and functions.
* Configuration macros and their usage.
* Explanations for each method and member.
* Error handling details.
* Correct calling sequence for initialization and usage.
* Relevant source code comments for methods, pin mapping, and event posting (if applicable).
* Example usage code.
 
Please provide the documentation in separate Markdown (.md) and reStructuredText (.rst) formats.

It did take a few iterations with each LLM but once the prompt is set, should be pretty quick to generate things.

As for the API's being stable, seems new functions are added quite regularly so better to have something than not.

Peripheral Manager API Docs.zip
ESP32 Ethernet API Documentation.zip

[pedrominatel]

Thank you, @Xylopyrographer, for bringing this topic back.
I'm ok with documentation being created by AI. We will need to review as we do for any new doc.
One thing we need to consider is adding a label on PRs prepared by AI, so the reviewer needs to take it into account.

Let me research if the LLM we have for our bot can be used to create docs.