Doxygen considered harmful
-
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.
... because of all the "Clicking the Print button prints the document" boilerplate. The problem here is that typical programmers aren't used to documentation, don't read documentation, much less their own. Don't blame the tool, blame the tool.
-
YvesDaoust wrote:
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.
It creates a reference, which should be part of the documentation; allows for quick lookups on the API and the syntax, but is indeed a lousy way of communicating it's use.
Bastard Programmer from Hell :suss: if you can't read my code, try converting it here[^]
Agreed.
-
YvesDaoust wrote:
Unless I am myself ignorant
Surprise[^] :-O Look for: \Page \subpage \section \subsection \subsubsection \paragraph \tableofcontents
Espen Harlinn Principal Architect, Software - Goodtech Projects & Services AS Projects promoting programming in "natural language" are intrinsically doomed to fail. Edsger W.Dijkstra
Yes they are there. They must be there. It is more that I have not see them in use. And, yes, Doxygen is not the true reason.
-
Ooh, don't go there. There be the monsters of out-of-date and unchecked examples, etc, that result in plumes of smoke coming out of customers' machines and ears. The only place to build a usage-oriented document is in a word processor.
I wanna be a eunuchs developer! Pass me a bread knife!
Good to know!
-
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!
All agreed.
-
Ooh, don't go there. There be the monsters of out-of-date and unchecked examples, etc, that result in plumes of smoke coming out of customers' machines and ears. The only place to build a usage-oriented document is in a word processor.
I wanna be a eunuchs developer! Pass me a bread knife!
Mark Wallace wrote:
The only place to build a usage-oriented document is in a word processor
And those documents are always up-to-date? I would usually start out writing stuff in Word, but quite often I end up with something that doxygen is able to consume :-)
Espen Harlinn Principal Architect, Software - Goodtech Projects & Services AS Projects promoting programming in "natural language" are intrinsically doomed to fail. Edsger W.Dijkstra
-
... because of all the "Clicking the Print button prints the document" boilerplate. The problem here is that typical programmers aren't used to documentation, don't read documentation, much less their own. Don't blame the tool, blame the tool.
You said the right thing(s).
-
Yes they are there. They must be there. It is more that I have not see them in use. And, yes, Doxygen is not the true reason.
YvesDaoust wrote:
Doxygen is not the true reason
I think I can heartily agree with that :)
Espen Harlinn Principal Architect, Software - Goodtech Projects & Services AS Projects promoting programming in "natural language" are intrinsically doomed to fail. Edsger W.Dijkstra
-
YvesDaoust wrote:
Doxygen is not the true reason
I think I can heartily agree with that :)
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.
-
Mark Wallace wrote:
The only place to build a usage-oriented document is in a word processor
And those documents are always up-to-date? I would usually start out writing stuff in Word, but quite often I end up with something that doxygen is able to consume :-)
Espen Harlinn Principal Architect, Software - Goodtech Projects & Services AS Projects promoting programming in "natural language" are intrinsically doomed to fail. Edsger W.Dijkstra
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!
-
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