Doxygen considered harmful
-
YvesDaoust wrote:
bloody, endless, uninformative Class Reference
Well, that's exactly what it is, so no problem. What it is not is a user guide/programming guide, so don't expect it to be one, but do complain if there isn't one. The general process is that developers refer to a user guide/programming guide until they've had a bit of practice, and then almost exclusively use the class reference. That's just how it works. Without the kick start of a user guide/programming guide, though, a class reference is just a pain in the @rse.
I wanna be a eunuchs developer! Pass me a bread knife!
Mark Wallace wrote:
bloody, endless, uninformative Class Reference
Well, that's exactly what it is, so no problem.
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.
-
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!
Mark Wallace wrote:
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.
Espen Harlinn Principal Architect, Software - Goodtech Projects & Services AS Projects promoting programming in "natural language" are intrinsically doomed to fail. Edsger W.Dijkstra
-
By the way, an opposite approach has been pursued by D. E. Knuth with his Literate programming approach. http://en.wikipedia.org/wiki/Literate_programming[^] This can probably be no better answer, for the same reaons.
As Peter said it: blame the tool. ;)
Espen Harlinn Principal Architect, Software - Goodtech Projects & Services AS Projects promoting programming in "natural language" are intrinsically doomed to fail. Edsger W.Dijkstra