You've been numerous to ask for documentation and the work of gass with GTK-doc help me to prioritize it, so this month I've finally tackled this problem but not as expected!
At first, I loved the GTK-doc solution, I'm a GNOME lover after all, but GTK-doc can't generate man pages and the setup code is too cumbersome IMHO. To choose the best solution for libmodbus, I read a comparison matrix on Wikipedia, after some tests with GTK-doc, Doxygen and AsciiDoc, and I finally choose AsciiDoc.
However, there is a major difference between AsciiDoc and the other envisaged solutions, the documentation isn't included in the source code. I used to think it was good idea to keep the both at the same place to keep them in sync but:
- it doesn't prevent you to code without updating the documentation
- the documentation must be escaped by the language comment tags
- I don't want to abuse my wheel mouse (to skip documentation) when I code
The 0MQ project, endless source of inspiration, was a very good starting point to learn some tricks with AsciiDoc.
Now, I'm looking for help to review and extend the documentation which has just landed in git (
make doc to generate man pages). I've generated the documentation in HTML for the web site.