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.

[AlfBaz]

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.

My rant aside, the question posed is in the title.

Whilst you can write up your documentation in doxygen's markup language and have no code whatsoever it's a retrograde step considering wysiwyg has been around for millennia, which brings us to doxygen's purpose, to extract documentation from the sources comments.

Whilst I agree that good code commenting is essential, in my humble opinion, source files are not the place for formatting documentation. Firstly it muddies up reading the code as andyturk mentioned and most importantly, because its in the source files it becomes the coders responsibility by default and is especially problematic in versioning and open source stuff. As an example, the code is written, debugged, tested and committed. Do you then allow somebody who hasn't written the code to go through it and add the formatting codes and expand/elaborate the comments? Then what bump the versioning because of changes to documentation?

A good coder is a good coder and may not have the linguistic or explanatory skills to write good documentation so why lump two distinct tasks in the one basket.

When code is being written that's all they should be concentrating on and when documentation is been written, that's all that should be concentrated on. You get one person doing to distinct tasks simultaneously and you end up with both half arsed code and documentation which bring us to the question I raised, is the entire premise of doxygen floored from the outset?

[nctnico]

@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.

Most managers just look at stuff as they would look at beads and mirrors. If it looks shiny it is okay by them  About a decade ago I had to examine code produced by an external programmer. He used doxygen to produce a PDF which basically listed all the functions. I didn't accept it as proper documentation. My manager did. I spend quite some time figuring out how the software worked exactly in order to finish it into the final software product.

@AlfBaz: the best way is to document/design first and then write code. Just starting often leads to massive rewrites.

[BravoV]

I didn't accept it as proper documentation. My manager did. I spend quite some time figuring out how the software worked exactly in order to finish it into the final software product.

What a lucky manager. 

[AlfBaz]

Just starting often leads to massive rewrites.

I've learnt that lesson far to may times

[Kohanbash]

My rant aside, the question posed is in the title.

Whilst you can write up your documentation in doxygen's markup language and have no code whatsoever it's a retrograde step considering wysiwyg has been around for millennia, which brings us to doxygen's purpose, to extract documentation from the sources comments.

In an ideal world you are correct people can but in practice most people dont go back and document their code. This is an attempt to get people who might already be doing inline documentation to do it while coding which also can work.

Whilst I agree that good code commenting is essential, in my humble opinion, source files are not the place for formatting documentation. Firstly it muddies up reading the code as andyturk mentioned and most importantly, because its in the source files it becomes the coders responsibility by default and is especially problematic in versioning and open source stuff. As an example, the code is written, debugged, tested and committed. Do you then allow somebody who hasn't written the code to go through it and add the formatting codes and expand/elaborate the comments? Then what bump the versioning because of changes to documentation?

I dont think it muddies up the code. It makes reading the src file easier to understand in many cases. If you are looking for something in a file you can look at the comment for the function to decide if that is where you need to look without delving into the code.

It is easier for opensource and versioning since now there is only one file to maintain instead of multiple files. I see no problem recommitting a file to your repo with better/fixed comments. That is a valuable change.

I agree that a separate technical writer can probably produce better documentation. But then you are also relying on that person who did not develop the code to get interpret it correctly (I have heard of people having a code review where they make the reviewer write the documentation and then the author confirms that it is correct).

[AlfBaz]

@sdk32285
We will have to agree to disagree.

To me commenting how source code functions is a world away from documenting the end use of said code and the proof is in the documentation currently available out there, most of it is just utter shite. Whilst you give examples and situations where workflows and quality outcomes can happen, inevitably it just doesn't.
Worst still it starts becoming the defacto standard and as time progresses less and less effort is put into decent documentation. Case in point are libraries from chip vendors where you have to run doxygen on the code yourself if you want documentation

[Kohanbash]

I am not saying it is great, just that it is not the worse.

As you said. I think we will have to agree to disagree.

Cheers!

[zapta]

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

I don't know if your complaint is about doxygen specifically or the concept of embedding rich text documentation in source file. If the later, Java APIs are documented with Javadoc and some of them are very detailed and informative, e.g. http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html .  Here is an example of a an open source class with rich javadoc annotation https://github.com/android/platform_frameworks_base/blob/master/core/java/android/view/View.java , and the formatted result http://developer.android.com/reference/android/view/View.html

At work we use Javadoc extensively and for external docs I try to loop in a technical writer (they know how to edit source file and use version control system). The general rule is that the doc should not repeat the obvious.

[jucole]

Good documentation is not easy nor quick to write and usually involves a great deal more than just an export of source code classes etc.

Once a customer asked for the source code to a project and we had to write a special tool to find and remove the rather bad language from thousands of lines of code that a developer had added.

[AlfBaz]

I don't know if your complaint is about doxygen specifically or the concept of embedding rich text documentation in source file.

Both really, the former encourages the latter.

Most of the documentation produced can at best, only be classified as a reference and usually only of any use to the code's author.

For some of the more complex software stacks out there you have to not only reference the given documentation but also some standard, some data sheet and most times a third party guide on the standard.

Back in the MS VC6 days you would highlight a function name, press F1 and everything you needed to know would pop up. The how, the why, links to detailed explanations of parameters and structures, what files to #include, what libs to add or dll's to import and related functions... I'm afraid this sort of documentation has spoiled me forever

[rollatorwieltje]

We have a rule that rich text does not belong in a source code file. Doxygen comments are there to give a quick impression on how to use a class and it's functions. Why a function or class exists is documented elsewhere.
However I have seen proper documentation in Doxygen as well. Doxygen doesn't just read source files, you can also make separate files for non-class specific documents, i.e. an introduction page, class overview, example pages etc. Graphvis is supported, so you can easily draw charts using that.
Also note that you don't have to use HTML garbage for rich text, it also has it's own Markup language that's vaguely similar to wiki markup. The plain text is still very readable when you use that.

[fagiano]

I agree, no docs in the source. I'm the technical director of a videogames company that does MMORPGs, so I deal with huge code bases of that are 90% our proprietary code. I always tell to the newcomers "I don't want to see a comment except if what you are doing is not obvious(eg. bitwise trickery)". Comments are rarely useful if you keep you code quality high(that should be the priority other than comments) and even worst they must be misleading as often they don't get updated after a change(OT: recently I've spent 4 hours debugging some code I copied from an NXP sample that had an old comment). We document what is necessary using wiki and some homebrew tool that spits out html and we only document api/interfaces, not the internals. Sometimes we write an "article" on how to approach a specific library/problem. IMHO If you are making a commercial sw package you want to have some hand written docs in a decent format as reference, but in the end the best is to write some good code samples that cover most of your features. I always start with the samples. So yes, I think doxygen/javadoc & Co. are crap  .

my 2 cents

ciao
Alberto

[zapta]

Once a customer asked for the source code to a project and we had to write a special tool to find and remove the rather bad language from thousands of lines of code that a developer had added.

Will it detect "This code is slower than molasses going uphill in January" ?

It a previous company, a customer that got the source code complained about this comment in our code. True story.

In another company, we were distributing code with full source code, this was the contract, we could not strip anything and the comments were part of the product. As a result, we had a rule, no comments whatsoever. This was a piece of software with 150 man year or so.

Personally I like javadoc and like comment. When I program, I first write the comment and then fill in below the implementation of that code section, that is, the 'what' follows by the 'how'. When I reading the code, you can just scan the comments and understand what is done.

[westfw]

Back in the late 1970's, DEC's "Runoff" text formatter had the ability to recognize comments in source code, pull them out and treat them as formatter source.  So you could put text formatting commands in your comments, run the source code through runoff, and wind up with a pretty printed document.

I did that once.  It was sort of neat, I guess.  But it wasn't really a very good idea then, and it doesn't seem to be much better now.

[T3sl4co1l]

Worst thing to ever hit documentation?

Programmers!  Duh!

Blame the writer, not the tools.  The best a tool can ever do is make dumb stuff like "a = a + 1 // increment a by one".

As a means of producing a structured document, JavaDoc and dOxygen are pretty neat.  I've used them before (not regularly, as I'm only a recreational programmer; though I dare assert, what code I do write is leaps and bounds nicer in structure, formatting and commenting than the average programmer's ), and they produce helpful documents as they should (when used accordingly, of course).  Nice thing about dOxygen, it has LaTeX output, so I can \input it right into a larger document (say, the design document of some embedded project) with little to no effort.  (I can also input and prettyprint code, in snippets or whole files at a time, with the Listings package, which dOxygen already uses by default when printing code verbatim).

Tim