|
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! - DD Ethel 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
|
|
|
|
|
Nagy Vilmos wrote: numpties who write the code and have no idea how to write useful comments
True enough, I use doxygen regularly - and so far I've been quite happy with the tool 
|
|
|
|
|
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...
|
|
|
|
|
YvesDaoust wrote: Unless I am myself ignorant
Surprise[^] 
Look for:
\Page
\subpage
\section
\subsection
\subsubsection
\paragraph
\tableofcontents
|
|
|
|
|
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
|
|
|
|
|
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.
|
|
|
|
|
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
|
|
|
|
|
|
As Peter said it: blame the tool. 
|
|
|
|
|
Is it as harmful as Dihydrogen Monoxide?[^]
====================================
Transvestites - Roberts in Disguise!
====================================
|
|
|
|
|
|
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 
if you can't read my code, try converting it here[^]
|
|
|
|
|
|
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.
|
|
|
|
|
... 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).
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
