Create API reference

[igrr]

Describe all the basic APIs and the libraries by adding documentation to the repository or to the wiki.

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[cimba007]

Is there a wiki yet?

[igrr]

Yes there is!
http://www.esp8266.com/wiki/doku.php?id=arduino-docs

[romanseidl]

I don't get why some autogenerated API-Doc should not be possible. Isn't there some toolkit one could use to autogenerate something which shows object functions and parameters?

I am getting tired of having to read code for that.

[devyte]

I think the last comment is still rather valid. While we do have readthedocs, I don't think we have an automated way to generate docs for an api reference, and we probably should.

[davisonja]

Doxygen! 😊

[igrr]

We have some success with Doxygen + Breathe + Sphinx/readthedocs setup, i think it can be replicated here. The only (obvious) thing is that all header files need to receive actual API documentation.

…

On Sun, Oct 22, 2017, 16:13 Julian Davison ***@***.***> wrote: Doxygen! 😊 — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#18 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AEJcek-90hCA_9vV2mrX3OhRSAcHdUu2ks5suvkZgaJpZM4D3bpT> .

[davisonja]

Presumably we're thinking more basic api parameter/return/side effect rather than usage examples in the source? Keeping main docs for that?

[igrr]

Not usage examples, just what Doxygen normally produces from header file comments. E.g. http://esp-idf.readthedocs.io/en/latest/api-reference/system/log.html#api-reference

…

On Sun, Oct 22, 2017, 19:51 Julian Davison ***@***.***> wrote: Presumably we're thinking more basic api parameter/return/side effect rather than usage examples in the source? Keeping main docs for that? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#18 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AEJcetta4mFu_r5t2Zp2PozUh-2oe5uEks5suyw9gaJpZM4D3bpT> .

[davisonja]

I've seen some people use Doxygen as full documentation. My experiments with that haven't led me to believe it has major advantages though. So it sounds as though we are thinking the same way.

[atesin]

i think we should have 4 separate documentations here (as i do in arduino)

• arduino api, on which esp8266-arduino api is "familiar" (available at https://www.arduino.cc/reference/en/)
• xtensa c/c++ documentation on which espressif sdk api was built from
• espressif sdk api, on which esp8266 arduino was built from
• esp8266 arduino documentation (core and libs)

maybe we can build some documentation from source code with doxygen, but unfortunately source code header files (".h" files) does not cointain enough comments... until i could be wrong, with {esp-path} as = %localappdata%\Arduino15\packages\esp8266\, the involved folders i had found so far are:

• xtensa = {esp-path}\tools\xtensa-lx106-elf-gcc\3.0.4-gcc10.3-1757bed\xtensa-lx106-elf\include
• core = {esp-path}\hardware\esp8266\3.0.2\cores\esp8266
• builtin libs = {esp-path}\hardware\esp8266\3.0.2\libraries

check this post also = https://www.esp8266.com/viewtopic.php?p=95142#p95142