I am undecided--Doxygen looks pretty good, as do one or two of the wiki style tools--javadoc has a lot going for it (except the presence of java in the name:).

I really like the D language approach of allowing you to embed the code within an html document. The compiler simply ignores the surrounding HTML.

Haskell has a similar concept called Literate Haskell. Again, the source code is embedded within the documentation, and the compiler simple ignores everything except the source code, in this case indicated by the presence of a '>' in the first column of the line. If that isn't present, the compiler ignores the line.

Generally speaking, html is not the greatest markup in the world, but it is, or at least can be, pretty simple, as evidenced by this site, and there are dozens if not hundreds of tools around for editing, indexing, creating TOCs etc.

It is also as ubiquitous as anything is ever likely to be. It would be a rare machine these days that doesn't have some form of HTML browser available, even if it is a text-only one like lynx.

And the tools available go much further in accommodating the needs of the user. The browser I am using allows me to zoom the display (increasing the size of fonts and graphics using Ctrl-mousewheel, which is very useful for those who's eyesight is not so good. It also has a (downloadable) option to verbalise the contents--if you are completely blind. HTML is far from perfect, but it isn't going away anytime soon, and it does bring a wealth of useful tools with it.

And for the CLI-only crowd, lynx is far more usable when browsing nested documentation (like IO::Socket*/ LWP::*) than perldoc or man.