DOXYGEN... Worst thing to ever hit documentation??

[AlfBaz]

[RANT_MODE]
I have yet to come across software documentation generated with doxygen, from source files that is the slightest bit useful.

I think the worst thing about it is that the coder is providing the comments in the source code that end up in the so-called help file. The coder is up to his balls in the code construct and forgets that the person looking to use some function or structure is doing so because they are looking for the convenience of not having to delve into the complexities of what ever thing is being wrapped.

Inevitably you have to traverse through the often convoluted tripe that passes as "code"
shit like...

Code: [Select]

IM_A_PEANUT_WELL_VERSED_IN_THE_ART_OF_CONVOLUTION x;
...
#define IM_A_PEANUT_WELL_VERSED_IN_THE_ART_OF_CONVOLUTION CONVOLUTION_CONSTRUCT
#define CONVOLUTION_CONSTRUCT CONSTRUCT
#define CONSTRUCT volatile
//in order of "Open definition"


More often than not have to refer to the datasheet/spec/standard that this api is trying to encapsulate at which point, WHAT'S the POINT...
I have come across parameter explanations where a param name is Value and the explanation is "an integer value" SERIOUSLY??

If you are going to provide open source, closed source, any source for public consumption, DONT unless you are willing to put in the work to provide decent documentation!
[/RANT_MODE]

Sorry for the rant... Just had to get that off my chest
Feeling much better now

[andyturk]

I hear ya, but what does the convoluted peanut have to do with oxygen? 

Is this not a reasonable example of how it should work: ChibiOS/RT Doc?

[AlfBaz]

I hear ya, but what does the convoluted peanut have to do with oxygen? 

Nothing, I was already patience-less when I started code hopping

Is this not a reasonable example of how it should work: ChibiOS/RT Doc?

That's an example of great work created by somebody that gave a shit

[Kohanbash]

Hi
I have used doxygen on several projects successfully. They key is to be strict about how and when comments are used in code.

I have found it useful when working on large projects with many developers. When the interfaces for functions are defined it makes using them easier and you can avoid looking at the code to determine what it does.

There are definitely short coming with it but I am not aware of any better options.

(sorry to rain on your rant)

[Maxlor]

I feel your pain. It's happened often enough that I found some open source library for a task at hand, but the documentation was so shoddily done that I ended up referring to the library's source code to figure out how to use it. Now I don't want to complain too much about something given for free, but I'd really appreciate a bit more thought given to a library's user.

Btw, having to read the source code to figure out how to use it has happened particularly often with arduino libs for some piece of hardware and another. And in 4 out of 5 cases, what I found there was so bad that I elected to roll my own instead. That's the drawback of making programming accessible, the resulting quality is atrocious, and it's hard to find the few gems that do exist :/

[Ed.Kloonk]

Who the hell documents their own code?

 

[Rerouter]

I do, at-least in the form of large comment blocks in the code explaining what each module / function does so that in 3 years time i can pick it back up in a few minutes vs a few days,

[codeboy2k]

Who the hell documents their own code?

 

I hope you're joking...

[Ed.Kloonk]

 

[Kohanbash]

Not necessarily doxygen but I am pretty strict with the people I work with about comments.
I expect every file, function, and class to have a comment. Also since we can have a bunch of directories each directory needs to have a README file with what it contains.

It takes longer to write the code but it saves time in the long run and helps other people know what is in the code.

[amyk]

There was an IDE plugin that would helpfully "generate" documentation for you from function names, parameters, etc. Unfortunately it would also produce stuff like

Code: [Select]

    ///
    /// Actions the list contains.
    ///
    /// The action list.
    /// Type of the action.
    ///
    public static bool ActionListContains(ActionType actionType)
    {
    }

    ///
    /// Geoes the lookup.
    ///
    /// The longitude.
    /// The latitude.
    ///
    public static GeoLocation GeoLookup(double longitude, double latitude)
    {
    }

    ///
    /// Windows the state of the update visual.
    ///
    /// The visual states.
    public void WindowUpdateVisualState(WindowStates visualStates)
    {
    }


[andyturk]

There was an IDE plugin that would helpfully "generate" documentation for you from function names, parameters, etc.

Meh. Filling up a file with "comments" generated from the code just makes it harder to see what's going on. What's really annoying is when all that useless verbiage spreads the interesting bits out so you can't see 'em on the screen simultaneously. I *hate* having to scroll up and down in order to figure out how the entry of a routine connects with the loop innards and/or exit.

Clever code is fine (assuming it works). Just warn me ahead of time and don't turn it into an easter egg hunt.

[Maxlor]

I've worked with people who were strict about commenting, und who were very proud of their very well commented code. Unfortunately, their comments often enough look like this:

if (myPin == HIGH) { // test whether myPin is HIGH
  switchOnLed(); // switch on the LED
}

You get the idea.

I'm all for commenting, but please, quality over quantity. I hate comments that just tell me what's happening, that's right there in the code already. The why's and on occasion how's are much more interesting, but also often unexplained. Oh well.

Btw, you can save yourself a lot of commenting by naming things well. A function called switchOnLed() doesn't really need comments that explain what it does. A variable called a on the other hand...

[Bored@Work]

It's garbage in - garbage out. No tool in the world can fix this. So why blame doxygen?

[filip_cro]

You called this bad? My first programming professor insisted on commenting every f***ing line of code on exams. But he tel that we can use only word end to comment '}'. 

[nctnico]

Hi
I have used doxygen on several projects successfully. They key is to be strict about how and when comments are used in code.

I have found it useful when working on large projects with many developers. When the interfaces for functions are defined it makes using them easier and you can avoid looking at the code to determine what it does.

Eclipse can do that in realtime. You don't need Doxygen for that.
I agree so much with AlfBaz I want to give him a hug and cry. Finally someone who has seen the light!

If you have to work on other people's software the most important question is why things are implemented in a certain way and how information flows through a piece of software. In what order do I need to initialise an API? Which parameters can be passed? What does it do? Doxygen cannot show that. For that you need proper documentation with diagrams (based on UML).

A couple of months ago I used NXP's version of Lufa to make a USB host. The documentation is generated with Doxygen and therefore utterly useless. It took me quite some time going through the examples and source code to figure out how to use the library.

[Kohanbash]

Hi
I have used doxygen on several projects successfully. They key is to be strict about how and when comments are used in code.

I have found it useful when working on large projects with many developers. When the interfaces for functions are defined it makes using them easier and you can avoid looking at the code to determine what it does.

Eclipse can do that in realtime. You don't need Doxygen for that.
I agree so much with AlfBaz I want to give him a hug and cry. Finally someone who has seen the light!

If you have to work on other people's software the most important question is why things are implemented in a certain way and how information flows through a piece of software. In what order do I need to initialise an API? Which parameters can be passed? What does it do? Doxygen cannot show that. For that you need proper documentation with diagrams (based on UML).

I do not use Eclipse so I can be wrong. But Eclipse is just an IDE. All of the documentation is done by using its user interface on top of documentation tools (such as doxygen, javadoc,RDoc, etc.. ).

As I said before it is based on how you (and your team) document. If every function/class has a short intro with an example of calling the function with its output then it works. If people do not get into that habit no documentation tool will work.

One project that I used it for had lots of plugin sensors that we could need and the list of sensors was always changing. By using doxygen you could just look up your sensor and know how to initialize it (if needed) and how to call it and with which parameters.

edit: I am not saying it is a perfect tool (far from it), I am just saying that it is not an awful tool that should be dismissed.

[Bored@Work]

You are shooting the messenger, doxygen. It just brings you the message that your programmers can't write documentation. They would write the same junk if you give them something else.

And by the way, doxygen can generate UML diagrams. If this floats your boat.

[nctnico]

Hi
I have used doxygen on several projects successfully. They key is to be strict about how and when comments are used in code.

I have found it useful when working on large projects with many developers. When the interfaces for functions are defined it makes using them easier and you can avoid looking at the code to determine what it does.

Eclipse can do that in realtime. You don't need Doxygen for that.
I agree so much with AlfBaz I want to give him a hug and cry. Finally someone who has seen the light!

If you have to work on other people's software the most important question is why things are implemented in a certain way and how information flows through a piece of software. In what order do I need to initialise an API? Which parameters can be passed? What does it do? Doxygen cannot show that. For that you need proper documentation with diagrams (based on UML).

I do not use Eclipse so I can be wrong. But Eclipse is just an IDE.

In Eclipse you just hover over a function and it shows you it's definition or if it is in the same project you can look at the source code in a floating window. It provides the same information as Doxygen but it updates in real time. Even working on the Linux kernel is easy with Eclipse.

@Bored@Work: Doxygen makes lazy programmers get away with not writing proper documentation. It looks nice at first glance but the essential information is missing. It is like having a house painted. It may look nice on the outside but if you have to repaint parts of it you may want to know why they used that particular paint and how they prepared the surface.

[Kohanbash]

In Eclipse you just hover over a function and it shows you it's definition or if it is in the same project you can look at the source code in a floating window. It provides the same information as Doxygen but it updates in real time. Even working on the Linux kernel is easy with Eclipse.

@Bored@Work: Doxygen makes lazy programmers get away with not writing proper documentation. It looks nice at first glance but the essential information is missing. It is like having a house painted. It may look nice on the outside but if you have to repaint parts of it you may want to know why they used that particular paint and how they prepared the surface.

I will conceded that having your IDE show you those floating windows is very useful. But doxygen lets you get more then just what you put your mouse over. If you are integrating a new module you can see example code, how to initialize or close the port, etc.. It is up to the programmer to make good documentation doxygen allows then to create the documentation in a distributed manor that then gets pulled together. I would argue that documenting as you go is better since it is fresh in your head rather then going back and documenting.

How does the IDE show the functions? Is it just the arguments and return value? that seems like it is missing the important comments by the programmers with detail and what to look out for.

I have seen entire user manuals prepared with doxygen.

[nctnico]

In Eclipse you just hover over a function and it shows you it's definition or if it is in the same project you can look at the source code in a floating window. It provides the same information as Doxygen but it updates in real time. Even working on the Linux kernel is easy with Eclipse.

@Bored@Work: Doxygen makes lazy programmers get away with not writing proper documentation. It looks nice at first glance but the essential information is missing. It is like having a house painted. It may look nice on the outside but if you have to repaint parts of it you may want to know why they used that particular paint and how they prepared the surface.

I will conceded that having your IDE show you those floating windows is very useful. But doxygen lets you get more then just what you put your mouse over. If you are integrating a new module you can see example code, how to initialize or close the port, etc.. It is up to the programmer to make good documentation doxygen allows then to create the documentation in a distributed manor that then gets pulled together. I would argue that documenting as you go is better since it is fresh in your head rather then going back and documenting.

How does the IDE show the functions? Is it just the arguments and return value? that seems like it is missing the important comments by the programmers with detail and what to look out for.

Eclipse also shows the comments. If you never used Eclipse you should really give it a try. Most IDE's primary function seems to be to cater noobs who don't use Emacs and makefiles. Eclipse OTOH has been developed to be the best IDE there is.

[Bored@Work]

@Bored@Work: Doxygen makes lazy programmers get away with not writing proper documentation.

No, their managers let them get away with it. Like with all documentation (or code), if you want quality you have to set quality standards and follow up, e.g. with documentation reviews, and you have to bring in experts, aka technical writers.

[codeboy2k]

I was once a big fan of literate programming.  That's from Knuth.

For those who do not know, you write the code by telling how it works ... ie. documenting it, and interspersing code fragments throughout the documentation, as references to the code. But these references become the actual code when you run the documentation through a preprocessor that extracts the code (which can be in any order that makes sense for documentation) and binds it together into working code that is then compiled.

So it's the exact opposite of the way documenters like Doxygen and JavaDocs works.  The code is a by-product of the documentation, not the documentation is a by-product of the code.

EDIT: by the way... this hybrid docu-code was written in TeX using macros that created a new language called WEB , and there were programs tangle and weave that converted the WEB file into source code file for compilation and a pure TeX file for documentation.

[Kohanbash]

In Eclipse you just hover over a function and it shows you it's definition or if it is in the same project you can look at the source code in a floating window. It provides the same information as Doxygen but it updates in real time. Even working on the Linux kernel is easy with Eclipse.

@Bored@Work: Doxygen makes lazy programmers get away with not writing proper documentation. It looks nice at first glance but the essential information is missing. It is like having a house painted. It may look nice on the outside but if you have to repaint parts of it you may want to know why they used that particular paint and how they prepared the surface.

I will conceded that having your IDE show you those floating windows is very useful. But doxygen lets you get more then just what you put your mouse over. If you are integrating a new module you can see example code, how to initialize or close the port, etc.. It is up to the programmer to make good documentation doxygen allows then to create the documentation in a distributed manor that then gets pulled together. I would argue that documenting as you go is better since it is fresh in your head rather then going back and documenting.

How does the IDE show the functions? Is it just the arguments and return value? that seems like it is missing the important comments by the programmers with detail and what to look out for.

Eclipse also shows the comments. If you never used Eclipse you should really give it a try. Most IDE's primary function seems to be to cater noobs who don't use Emacs and makefiles. Eclipse OTOH has been developed to be the best IDE there is.

I have used eclipse for some specialty applications (mostly the Xilinx SDK is based on it) but I have never given it a real try. I have been using vim (and make files) for over a decade now so I just like it and can use it quickly.

[dannyf]

You have to recognize that doxygen is only a tool. As such it is only as good or bad as the person using it.