generate API docs for Firmata

[soundanalogous]

Use Doxygen or other doc generator to create documentation for the Firmata library. This will require adding appropriate doc commentes to Firmata.h and Firmata.cpp.

Anyone have a preference for a C++ doc generator?

[mexchip]

I'd like to help with this. At first glance, most code is documented and would only need to set up Doxygen, is it correct?

[soundanalogous]

That would be great! Setting up Doxygen is a good first step, code comments were greatly improved since I filed this request, but we'd have to inspect the output of Doxygen to see if any changes are necessary. My initial thought is adding a /docs/ directory for the Doxygen output is probably the simplest path and then I can enable github-pages pointing to that /docs/ directory as described here.

[mexchip]

I've set up doxygen at the fork here: https://github.com/mexchip/arduino/tree/doxygen-docs

And also integrated into the fork's master to be able to set github pages as per the guide you suggested, so that you can have a look at how it looks: https://mexchip.github.io/arduino/

Please let me know what you think.

[soundanalogous]

That was quick :D. For now we can set the readme as the main page. Looks like you can do that by setting USE_MDFILE_AS_MAINPAGE to readme.md in the Doxyfile as that referenced article author does in a later commit here.

Other than that this is a good start. I will override the css at some point to at least flatten the appearance of the header bar so it doesn't look so iPhone 2006 LoL.

[mexchip]

Didn't know about that option! I've added it: https://mexchip.github.io/arduino/

Previously, I tried adding readme.md but had to add {#main_page} tag to current readme.md to make it appear on docs main page, but github doesn't hide those tags and it would appear in the repo main page too.

[mexchip]

Other than that this is a good start. I will override the css at some point to at least flatten the appearance of the header bar so it doesn't look so iPhone 2006 LoL.

Yes, default doxygen style looks a bit outdated today 😝

[mexchip]

I've added a .nojekyll file to fix doxygen generated html files that start with underscore not showing on github pages, as stated here: https://github.blog/2009-12-29-bypassing-jekyll-on-github-pages/

I also searched for some doxygen themes and applied this one: https://github.com/Velron/doxygen-bootstrapped

The problem with this doxygen theme it that it does not work with doxygen versions >=1.8.12 (Velron/doxygen-bootstrapped#20)

I generated the docs using doxygen 1.8.11 (had to compile it), I guess it'd be a problem whenever someone needs to rebuild the docs, what do you think?

[soundanalogous]

Thanks for taking the time to look into alternate themes. However, I would like to avoid being constrained to a specific doxygen version just to have an alternate theme. Let's keep the default theme for now and I'll experiment with overriding the css and custom headers after your branch is merged.

[mexchip]

Thanks for taking the time to look into alternate themes. However, I would like to avoid being constrained to a specific doxygen version just to have an alternate theme. Let's keep the default theme for now and I'll experiment with overriding the css and custom headers after your branch is merged.

Ok 👍

[soundanalogous]

Thanks again for your help on this! Let me know if you think anything is missing documentation-wise. For example, I've been debating whether or not I should add the constants from FirmataConstants.h.

[mexchip]

It was a pleasure!
I think constants should be added, so that they could be referenced in functions needing them as parameters.