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, no programming
questions and please don't post ads.
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.
0thly, I do not use Doxygen and I had to look it up; you can do that on the interweb.
It doesn't look that bad an idea, but I submit to you that that is not the problem. The problem is in the numpties who write the code and have no idea how to write useful comments.
Panic, Chaos, Destruction. My work here is done.
Drink. Get drunk. Fall over - P O'H
OK, I will win to day or my name isn't Ethel Crudacre! - DDEthel Crudacre
I cannot live by bread alone. Bacon and ketchup are needed as well. - Trollslayer
Have a bit more patience with newbies. Of course some of them act dumb - they're often *students*, for heaven's sake - Terry Pratchett
My point is: not only. Unless I am myself ignorant, Doxygen provides no place to shape a well-structured document with chapters, sections, titles, narrative comments... and all the samples I have seen were in the same vein.
Probably am I naive to hope that a tool used for internal purposes by the maintainers of the code satisfies the users too...
You could, but once it's inside the codebase, you've lost it, and so has anyone who has to check that it's up to date, correct, etc.
And that's not to mention that the examples will be scattered all over the shop, with no way of knowing if they're in a good place that will be found by the developers looking for them -- an example for the CListCtrl class, for example, could contain a perfect one-line code example of using an "IceBox" object and its "keepBeerCool" method, which will never be found when developers search for a solution for their beer warming up, because, well, because they're wisely not using CListCtrl, are they?
If, on the other hand, all the usage-centric/use-case examples are in a word-processor document, it's dead easy to keep track of them all, dead easy to distribute them to people for checking/confirmation/etc, and dead easy for users (i.e. the poor mugs doing the developing with warm beer)to find them.
I wanna be a eunuchs developer! Pass me a bread knife!
usage-centric/use-case examples are in a word-processor document
I have no problem with that ...
But then we have the documentation that's mostly for other developers.
Given that many of us work with rather standardized directory structures that quite often have a \docs directory - which is a logical place to keep a makefile that's responsible for keeping the stuff up-to-date - it shouldn't be all that hard to figure out.
Well, there is in fact a problem if the class reference is, as the OP said, uninformative, and most are. Constructor documentation that says "Instantiates a new instance of MyClass." is as useful as a chocolate teapot.