Documentation Auto-gen Tools for C

Moderator
Posts: 3,579
Joined: 2003.06
Post: #1
I've forced myself to add a little comment header above every function in recent years, since I've discovered over time that I don't always remember what a particular function was for, which I may have written 5+ years ago for some odd task. It used to bug the heck out of me to see other people pollute their code with massive documentation, but ironically, as my own projects have routinely grown to 50kloc+, I've discovered that I don't mind the pollution as much as forgetting how something works!

So... Since I am now mandatorily adding a function comment header over every function, I am starting to wonder if it would make sense to go the extra step and use something like Doxygen?

I program about 90% in C. Does anyone here have any recommendations outside of Doxygen? Should I not bother with documentation auto-gen tools? Any other advice or opinions about documentation?
Quote this message in a reply
Sage
Posts: 1,482
Joined: 2002.09
Post: #2
I don't really like Doxygen. It seems really overcomplicated and doesn't make the nicest looking docs for C code. (I do rather liked the Ruby and Java doc generators) On the other hand... I've never found anything else that's even close to as good as Doxygen, so I use it anyway.

Scott Lembcke - Howling Moon Software
Author of Chipmunk Physics - A fast and simple rigid body physics library in C.
Quote this message in a reply
Moderator
Posts: 3,579
Joined: 2003.06
Post: #3
So then +1 for Doxygen being about the only reasonable option for C doc gen at this point I guess. Fingers crossed someone chimes in with a better suggestion, but if you haven't seen one yourself, Skorche, my hopes are fading quickly.
Quote this message in a reply
Luminary
Posts: 5,143
Joined: 2002.04
Post: #4
HeaderDoc!
Quote this message in a reply
Moderator
Posts: 3,579
Joined: 2003.06
Post: #5
I had completely forgotten about HeaderDoc. From the outside, it appears to be a good alternative to Doxygen for C. I'll definitely have to look into it.
Quote this message in a reply
Sage
Posts: 1,482
Joined: 2002.09
Post: #6
HeaderDoc? Really? Rasp You are just saying that because you work at Apple. I don't remember why, but I had some issue with HeaderDoc. Maybe it didn't parse some C stuff quite correctly? I forget...

The big issue I had with HeaderDoc though is that it's output is very hard to navigate. It seems like it just creates big huge linear lists with a minimal amount of linkage or navigation. When you want to find something in the document, your best bet is to use the browser's find command. The same problem as with Apple's docs for large libraries, but with a far more ugly default stylesheet.

Scott Lembcke - Howling Moon Software
Author of Chipmunk Physics - A fast and simple rigid body physics library in C.
Quote this message in a reply
⌘-R in Chief
Posts: 1,265
Joined: 2002.05
Post: #7
Funny. I always find Doxygen docs to be harder to navigate. Annoyingly HeaderDoc didn't used to make as pretty of pages as Apple has, but I think they changed that sometime back? I haven't used it in a long time.
Quote this message in a reply
Sage
Posts: 1,482
Joined: 2002.09
Post: #8
Granted, Doxygen's navigation isn't perfect for C. It's much better for OO languages, but with C it requires a lot of marking using "modules". In the end you still end up with something like this: http://chipmunk-physics.net/release/Chip...index.html

Scott Lembcke - Howling Moon Software
Author of Chipmunk Physics - A fast and simple rigid body physics library in C.
Quote this message in a reply
Moderator
Posts: 1,562
Joined: 2003.10
Post: #9
I did some research a while ago on tools for this, and really couldn't find any I liked. If I recall, both Doxygen and HeaderDoc produced unsatisfactory output, with way too much fluff in the way of the info I actually wanted. I've been writing simple banner comments in header files, and it works OK - it's certainly not the easiest thing to navigate, but the information is there when you need it, and is tied directly to the code so you don't have the potential to be looking at the wrong version of documentation for what you're using.
Quote this message in a reply
Moderator
Posts: 3,579
Joined: 2003.06
Post: #10
Thanks for all the input!

So far, HeaderDoc seems to be working okay for me. It is pretty friggen' simple to use, but I haven't pushed it yet, so there may be lurking issues awaiting me. The html output actually looks pretty nice to me. The search thing might be a problem.
Quote this message in a reply
Moderator
Posts: 3,579
Joined: 2003.06
Post: #11
Update: Well, it was working *okay* (see below for pros and cons) for making the individual page for each header, but when I run gatherheaderdoc to make the master table of contents it outputs many messages about "Use of uninitialized value $TOCTemplate" ... blahblahblah", and the masterTOC.html comes out with an empty page. The only thing in the source of the page is:

Code:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">

So something is either wrong with it or I did not understand the docs correctly (if so, the docs need help, because I RTFM). I did find a similar bug report and tried out the fix, but no dice. I know nothing about perl scripts, and after searching around for a while, I have come up empty-handed. My long-shot hunch is that since the tools have been migrated into the Xcode bundle, it's not finding what it expects to find, where it expects to find it, but I haven't a clue about how to attempt a fix.

As far as "okay", here is my take on HeaderDoc after fiddling around with it for a total of about maybe two days, spread over the last two weeks.

Pros:
- It is easy to get started with.
- It is included with Xcode.
- Page generation looks acceptable if you don't need frills. There are three similar style options of generation.

Cons:
- Inflexible output options.
- It forces code formatting the way it wants, which is acceptable to me, but I can easily imagine others not liking it at all.
- Definitely do not like the way it breaks up my function declarations into a line for each parameter. This would be fine if it allowed a parameter description after it on that line, but it doesn't, so this is an incredible waste of vertical space, and simply unnecessary.
- Quirky C parsing output issues. Already I have found weird things like it'll format a #if/#else/#endif in an enum one way if the constant has a comma at the end of the line and another way if it does not, although this can be worked around by rearranging constants.
- When I ask to display warnings about untagged parameters (the -t option), a variadic function's "..." should not be forced to count as a parameter.
- Does not appear to have much support online. Many searches for tutorials and tips turn up very little.
- gatherheaderdoc does not currently work for me, which makes headerdoc as a whole useless at this point, unfortunately.
Quote this message in a reply
Moderator
Posts: 3,579
Joined: 2003.06
Post: #12
UPDATE 2: I figured out what happened. That page that I linked to with the bug fix was actually correct. The problem was that I was modifying the wrong "gatherheaderdoc" script. The one that is actually used is /usr/bin/gatherheaderdoc, which was specified in the error output that I wasn't paying attention to. I was modifying the one in the Xcode bundle, which obviously did nothing.

The master table of contents page is excessively dull, but hey, at least it works now.
Quote this message in a reply
Post Reply 

Possibly Related Threads...
Thread: Author Replies: Views: Last Post
  User Generated Documentation Talyn 1 2,297 Oct 13, 2008 06:29 AM
Last Post: Talyn