At work I do server programming in Java and after a while I guess you start to get erronous idea that all automatic docs are like javadoc or better.
Oh, so rdoc (Ruby) sucks like the end of the world, and ri is a joke, but those are just exceptions - right?
...or so I thought until I tried to look at some Doxygen documentation for LLVM... It made me want to claw my eyes out to make the horrible thing go away.
I mean WHAT IS WRONG WITH THE WORLD people!? Look, when old-timers man and javadoc still is the cutting edge, you know you're in a really sad place.
I thought the Objective-C documentation was pretty bad, but it's like a shining beacon of light in comparison.
The bat-crazy thing is that people write stuff like "I love Doxygen, it is teh bestest", like there is even a remote possibly it could be true.
I read one exchange where people argued that the reason Doxygen docs sucked - everywhere - was because people didn't configure it right and didn't stick with the conventions...
I hate to break it to you people but it is a f*****g tool, and a tool is supposed to help, not make you spend hours in configuration and figuring out best practices. So if your so-called tool isn't helpful, you're way better off writing the docs by hand - and I don't care if the tool creates some fancy but utterly unusable class diagrams, it is still worthless.
Javadoc and man already shows exactly what any documentation at least have to live up to.
It is really easy, here is a check-list on what an auto-doc tool needs.
1. Great formatting.
Not "acceptable", not "good". It has to be great. You already had to break your coding flow to look something up, so the formatting needs to be crisp sharp to guide you to exactly the information you need as fast as possible so you can get back as fast as possible.
2. Zero configuration.
Configurable tools suck, yes they suck. Because most of the time "configurability" is nothing more than an excuse for the tool coder not to figure out good defaults for you.
Yes it is worthwhile to have some configurable parameters, but it should be the exception rather than the rule. If things are configurable, then doc A and doc B will look different, and a programmer used to look at docs generated with style A will be confused by style B and vice-versa. In documentation, consistency is king.
Obviously this has to be language specific, but within a language the docs should look the same. If you are making a tool and plan to make the user to configure everything, then you are a lazy bastard.
3. Well thought out and clear doc conventions
Your tool should make it easy for a programmer to know what the can make the auto-doc tool improve the documentation.
Start looking at Javadoc - it is not great but it works. We have the basic @param, @throws and @return. It should be easy to expand that and adapt specific conventions for each language.
4. Remember the needs of the programmer.
Find the common use cases and optimize for them.
When programming Java, in the majority of cases I look up docs for one of three reasons:
1. To find the correct method to call on a class.
2. To understand the workings of a method of a class.
3. To find the correct class to use in a library/framework.
Javadoc is fairly optimized to for this: It's easy to scroll through the methods. If you click a method then the description gives you the basic arguments, and there is a doc convention to describe the most important information (parameters, return value, when exceptions are thrown).
It is also easy to find a class due to the package structuring and the quick links to implementing classes/subclasses.
Automatic documentation is a solved problem. Too bad no-one seems to be looking at the solutions.
I'm going to finish with a quote from the Qt-list:
"It's [blaming Doxygen for the bad documentation], or blame almost every single user of the tool. At this point, I'd prefer to blame the tool."
0 comments:
Post a Comment