How about Doxygen?

I recently (re)discovered Doxygen for automating code documentation:

http://www.stack.nl/~dimitri/doxygen/index.html

For the first time I can't wait to go home from work to document my library code. Any comments on this tool? Should I/we suggest other arduino software writers and library developers to use it?

Doxygen is great. I often use it for reverse engineering. However for such small stuff like the Arduino libraries I prefer to see the actual code. For me this is easier to read and understand than long wound library documentation.

Documentation often comes with a price. The same is true for doxygen. The biggest issue is that it clutters your source code. The other issue is generic: documentation creates additional overhead / double maintenance.

IMHO I would like to see integrated version control (e.g. git) before there is more documentation support. Right now most Arduino stuff is small enough to go with C comments.

[quote author=Udo Klein link=topic=87038.msg652598#msg652598 date=1326529293] Doxygen is great. I often use it for reverse engineering. However for such small stuff like the Arduino libraries I prefer to see the actual code. For me this is easier to read and understand than long wound library documentation.

Documentation often comes with a price. The same is true for doxygen. The biggest issue is that it clutters your source code. The other issue is generic: documentation creates additional overhead / double maintenance.

IMHO I would like to see integrated version control (e.g. git) before there is more documentation support. Right now most Arduino stuff is small enough to go with C comments. [/quote]

My recent phi_interfaces library is 1,000 lines of code with a moderate complex class hierarchy. It's all working after testing. Without a decent doc, I am procrastinating its release. I have to use Doxygen. You will be confused just reading the codes.

I type comments while coding anyway so it's not much overhead especially if you want others to use the code. I don't see why double maintenance is needed though. Do you mean modifying the doc after it's automatically generated?

Doxygen is fine with >1000 lines of code.

I talk about libraries that have lots of small functions that can be understood on their own. Like e.g. math.h eeprom.h and similar one. Most of the Arduino core libraries are just very small wrappers of avr-libc, for avr-libc there is doxygen documentation which is fine. For Arduino there is none which is OK as well.

Not having seen your libraries I can not judge if I would use doxygen or not.

I don't know how to auto-document #define lines Any trick?

I am still working on documenting and have not written overviews yet.

http://liudr.files.wordpress.com/2012/01/refman.pdf

Doxygen rocks. I wished all library writers used it, like with RF24 Documentation. It's super handy to have the docs right there with the code, so when you change one it's easy to change the other.

I don't know how to auto-document #define lines

http://www.stack.nl/~dimitri/doxygen/commands.html#cmddef

Only works for files with a @file command at the top.

Thanks. What I was asking but not stating clearly about was how to document define values such as #define delay 200. So I will have a list of these values on the doc.

Was that not answered by the link above?

maniacbug: Was that not answered by the link above?

Thanks. I got this to work by using the "\file" inside my include file. Now the last section of the auto-doc includes a file documentation section with brief descriptions of what the include file has, classes etc, INCLUDING the #include lines. I'm happy. There's just few kinks but I'll do the following:

Do my best to get an auto-doc for the tech-intensive readers and do a parallel primer doc for just casual users to glance at, with sample codes. I'll be able to roll out my new library hopefully today.