Welcome to the Lounge
For lazing about and discussing anything in a software developer's life that takes your fancy.
The Lounge is rated PG. If you're about to post something you wouldn't want your kid sister to read then don't post it. No flame wars, no abusive conduct and please don't post ads.
Technical discussions are welcome, but if you need specific help please
use the programming forums.
|
|
 |
|
For the Nth time in my developer's career, I came across an API which was documented using Doxygen. (For the sake of mercy, I won't name it.)
As usual, all you are entitled to is a very terse introductory page, accompanied by the bloody, endless, uninformative Class Reference. As a bonus, you also get that wonderfully useless File List.
This way to document software drives me mad. It forces you to scan the whole API before you know if the functionality suits your needs, and gives you no hint on the philosophy of the stuff. This turns the discovery of otherwise valuable products into a painful guesswork and causes the learning curve to raise vertically.
I put most of the blame on Doxygen, because it gives programmers a false feeling that they did document their API, and that they did it in a "lush" way. I put the blame on Doxygen because of the poor presentation style it spreads and legitimizes, which favors form over content.
|
|
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Rant 
Admin
Submit an article or tip
Post your Blog
