Documentation - Why not doxygen?

[TheSlowGrowth]

I wonder if it would be possible to use doxygen for the documentation. Many editors support it out of the box or via plugins which helps enormously. Doxygen also allows for inline code examples, automatic links and many other neat features. I guess there were good reasons to use the custom python solution - if there were technical problems that prohibited doxygen, I could offer help to make it work.

[stephenhensley]

In the early stages we discussed several different documentation systems.

We landed pretty quickly on using inline documentation of some sort to limit the number of places that documentation would have to be maintained.

the makedoc.py was already a part of someone's external project, and took minutes to get up and running to generate markdown documenation, and I already use pandoc to generate manuals and such for other projects.

So, in short, it was a fast implementation that used a bunch of tools that we were familiar with.

On top of that, I personally feel that the inline markdown is readable, without being too cluttered/ugly in the header files (though, they can only look so nice when they're filled with comments).

These are, of course, my opinions. And I would be open to exploring other options if they can provide better documentation, cleaner looking headers, or some other benefit that is currently absent from the documentation.

[TheSlowGrowth]

Yes, I agree that inline documentation is the only sensible solution. Doxygen works exactly like that but has a couple of key advantages over a custom solution:

• doxygen can generate a wide range of output formats, including html (which could directly be hosted via github and even updated automatically via git hooks), tex and others. Imagine the DaisySP docs being hosted directly here on github. Users could just have a bookmark to the docs in the browser, how neat is that?!
• doxygen makes the documention easily searchable by automatically replacing type names with links to the corresponding doc pages, providing search functions and class index, etc. See here for an example: http://xerces.apache.org/xerces-c/apiDocs-3/classes.html
• doxygen is widely supported by code editors, allowing to highlight the doc comments, automatically generate (and check) the inline comment blocks; including descriptions for parameters, types, etc. This speeds up writing the documentation enormously and will improve the documentation quality
• doxygen allows to throw errors when documentation is missing or incomplete (e.g. when a function parameter name was changed but not the corresponding documentation). This helps keep the docs up to date. Combine this with a git hook for pull requests - instant improvement!
• doxygen has many formatting options (including "see here", "code blocks", "warnings", etc) that make both the final documentation as well as the inline comments easy to read.
• doxygen allows to create main pages and wiki-style pages right from the actual code itself, without making the code unreadable. This allows to easily create "quick start" pages that contain (automatically generated) links to the corresponding documentation.
• doxygen can be configured easily and generated via a simple cross platform GUI program (great for new developers) - or via a single executable that can be run from the command line as part of a git hook. The executable could be included in this repository, along with some sort of "makedoc.py" script
• doxygen is so full featured and wide-spread that it can be considered practically maintainance-free.

I'm not sure if you'd be open to give it a try. I could create a pull request and convert some of the existing docs to doxygen so we can give it a try and see if it works out

[TheSlowGrowth]

I have added a Doxyfile with corresponding settings. README.md is automatically used as the main page. I adjusted the AdEnv documentation to the doxygen style. We could probably even use a script to convert things en masse.

Give it a try: Run doxygen Doxyfileand observe the results in doc/html/index.html

[stephenhensley]

Yeah, you've definitely piqued my interest. Looks like a lot of benefits here.

I'll check out what you've got and what it generates now, and chime back in a few.

[stephenhensley]

okay, yeah. That's pretty amazing.

Lot's of very cool stuff built into it (even a compiled todo list!)

I think I'm in. Plus the lack of // ~~~~ as a code-detection block is a plus.

Installing doxygen on windows was super easy, so I'm guessing it'll be easy on Linux/OS X as well, (likely much easier than pandoc). And as you mentioned we can host it on the github.io site along with our usb uploader, etc.

[TheSlowGrowth]

Great. If you want, I can continue to port some of the existing documentation. I'll push this to my branch and replace the existing makedoc.py with something that runs doxygen and (if installed) LaTEX to make a pdf file as well. I'll open a pull request when I'm done.

Installing on OSX is as simple as A) download the GUI app B) brew install doxygen

[stephenhensley]

Awesome. That would be great!

Thanks for the contributions!

Once we've got this set up here. I can work on making a script to do the same to the libdaisy repo as that's already a lot larger than this lib.

[TheSlowGrowth]

If docs could be reformatted automatically (at least most of it) that would speed things up enormously. I'm not familiar enough with the current inline doc format to do this, but I guess with some clever regex magic it should be possible.

If you'll make a script anyways, I'd rather not redo all the existing doc manually... Maybe we can do the bunch of the work automated and do final touchups by hand.

[TheSlowGrowth]

Right now, the style guide is still done via pandoc. If we could integrate it into the doxygen as an extra page, we could remove the pandoc dependency. Otherwise, it can also stay as it is. pandoc was easy to install for me on OSX.

Let me know how to proceed with the conversion of the existing docs. After all docs are complete, I'd like to make doxygen abort on a warning. This will help to enforce a consistent documentation. Of course, right now, it spits tons of warnings because apart from AdEnv nothing is documented yet.

[stephenhensley]

Okay. I can look into making a script this afternoon. Should be relatively simple to get it most of the way there and then cleaning up.

If you want to make a PR for the initial setup. I can merge it to a new documentation branch and can clean some stuff up for there.

Let's leave the style guide until that's done, but then we might as well squeeze that into doxygen as well. No need to have pandoc if we don't need it (some of the pdf engine stuff is quite annoying to deal with on a cross-platform basis)

[TheSlowGrowth]

Great, I'll do that.

Regarding the style doc: I have some wishes for that as well, but I understand that there is a lot of code already based on it and many things boil down to preferences. Are you currently actively discussing the style guide? If so, I'd love to participate.

[stephenhensley]

@TheSlowGrowth

Awesome. I'll get this merged in a little bit and start working through the script for fixing up the previous inline documentation. I'll probably start working on this in a 'documentation' branch here.

I'm going to start setting up the electrosmith.github.io page to host the documentation (and an initial version of a usb-dfu programmer) this weekend as well.

As for the style guide: we had a discussion thread open a long time ago, but I'll open up something new to discuss. After actually using everything a bit, there are a few things I'd like to change as well (i.e. const reference arguments where it is actually a bit of a hindrance, like for setters).