DOXYGEN... Worst thing to ever hit documentation?? - Page 1
Forum section: electronics / general

author: AlfBaz
author_rank: Super Contributor
timestamp: January 05, 2014, 03:04:34 am
content: 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: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 isValueand 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!Sorry for the rant... Just had to get that off my chestFeeling much better now

author: andyturk
author_rank: Frequent Contributor
timestamp: January 05, 2014, 03:11:21 am
content: 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?

author: AlfBaz
author_rank: Super Contributor
timestamp: January 05, 2014, 03:18:21 am
content: Quote from: andyturk on January 05, 2014, 03:11:21 amNothing, I was already patience-less when I started code hoppingQuoteThat's an example of great work created by somebody that gave a shit

author: Kohanbash
author_rank: Regular Contributor
timestamp: January 05, 2014, 04:03:50 am
content: HiI 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)

author: Maxlor
author_rank: Frequent Contributor
timestamp: January 05, 2014, 04:15:52 am
content: 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 :/

author: Ed.Kloonk
author_rank: Super Contributor
timestamp: January 05, 2014, 04:16:48 am
content: Who the hell documents their own code?

author: Rerouter
author_rank: Super Contributor
timestamp: January 05, 2014, 04:34:47 am
content: 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,

author: codeboy2k
author_rank: Super Contributor
timestamp: January 05, 2014, 05:25:02 am
content: Quote from: Ed.Kloonk on January 05, 2014, 04:16:48 amI hope you're joking...

author: Kohanbash
author_rank: Regular Contributor
timestamp: January 05, 2014, 05:53:21 am
content: 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.

author: amyk
author_rank: Super Contributor
timestamp: January 05, 2014, 05:54:08 am
content: There was an IDE plugin that would helpfully "generate" documentation for you from function names, parameters, etc. Unfortunately it would also produce stuff likeCode:////// 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){}

author: andyturk
author_rank: Frequent Contributor
timestamp: January 05, 2014, 06:10:01 am
content: Quote from: amyk on January 05, 2014, 05:54:08 amMeh. 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.

author: Maxlor
author_rank: Frequent Contributor
timestamp: January 05, 2014, 07:45:15 am
content: 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 HIGHswitchOnLed(); // switch on the LED}You get the idea.I'm all for commenting, but please, quality over quantity. I hate comments that just tell mewhat's happening, that's right there in the code already. Thewhy's and on occasionhow'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 calledaon the other hand...

author: Bored@Work
author_rank: Super Contributor
timestamp: January 05, 2014, 12:01:35 pm
content: It's garbage in - garbage out. No tool in the world can fix this. So why blame doxygen?

author: filip_cro
author_rank: Regular Contributor
timestamp: January 05, 2014, 12:55:31 pm
content: 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 '}'.

author: nctnico
author_rank: Super Contributor
timestamp: January 05, 2014, 01:31:48 pm
content: Quote from: sdk32285 on January 05, 2014, 04:03:50 amEclipse 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.

author: Kohanbash
author_rank: Regular Contributor
timestamp: January 05, 2014, 01:40:43 pm
content: Quote from: nctnico on January 05, 2014, 01:31:48 pmI 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.

author: Bored@Work
author_rank: Super Contributor
timestamp: January 05, 2014, 01:45:01 pm
content: 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.

author: nctnico
author_rank: Super Contributor
timestamp: January 05, 2014, 01:46:28 pm
content: Quote from: sdk32285 on January 05, 2014, 01:40:43 pmIn 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.

author: Kohanbash
author_rank: Regular Contributor
timestamp: January 05, 2014, 02:00:52 pm
content: Quote from: nctnico on January 05, 2014, 01:46:28 pmI 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.

author: nctnico
author_rank: Super Contributor
timestamp: January 05, 2014, 02:17:14 pm
content: Quote from: sdk32285 on January 05, 2014, 02:00:52 pmEclipse 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.

author: Bored@Work
author_rank: Super Contributor
timestamp: January 05, 2014, 02:22:06 pm
content: Quote from: nctnico on January 05, 2014, 01:46:28 pmNo, 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.

author: codeboy2k
author_rank: Super Contributor
timestamp: January 05, 2014, 02:25:17 pm
content: 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 referencesbecome the actual codewhen 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 programstangleandweavethat converted the WEB file into source code file for compilation and a pure TeX file for documentation.

author: Kohanbash
author_rank: Regular Contributor
timestamp: January 05, 2014, 02:29:14 pm
content: Quote from: nctnico on January 05, 2014, 02:17:14 pmI 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.

author: dannyf
author_rank: Super Contributor
timestamp: January 05, 2014, 02:35:17 pm
content: You have to recognize that doxygen is only a tool. As such it is only as good or bad as the person using it.

author: AlfBaz
author_rank: Super Contributor
timestamp: January 05, 2014, 02:37:38 pm
content: Quote from: Bored@Work on January 05, 2014, 01:45:01 pmMy 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?

author: nctnico
author_rank: Super Contributor
timestamp: January 05, 2014, 03:04:11 pm
content: Quote from: Bored@Work on January 05, 2014, 02:22:06 pmMost managers just look at stuff as they would look at beads and mirrors. If it looks shiny it is okay by themAbout 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.

author: BravoV
author_rank: Super Contributor
timestamp: January 05, 2014, 03:06:31 pm
content: Quote from: nctnico on January 05, 2014, 03:04:11 pmWhat a lucky manager.

author: AlfBaz
author_rank: Super Contributor
timestamp: January 05, 2014, 03:10:32 pm
content: Quote from: nctnico on January 05, 2014, 03:04:11 pmI've learnt that lesson far to may times

author: Kohanbash
author_rank: Regular Contributor
timestamp: January 05, 2014, 03:30:38 pm
content: Quote from: AlfBaz on January 05, 2014, 02:37:38 pmIn 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.Quote from: AlfBaz on January 05, 2014, 02:37:38 pmI 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).

author: AlfBaz
author_rank: Super Contributor
timestamp: January 05, 2014, 03:58:19 pm
content: @sdk32285We 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

author: Kohanbash
author_rank: Regular Contributor
timestamp: January 05, 2014, 04:01:33 pm
content: 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!

author: zapta
author_rank: Super Contributor
timestamp: January 07, 2014, 05:14:34 pm
content: Quote from: AlfBaz on January 05, 2014, 03:04:34 amI 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 annotationhttps://github.com/android/platform_frameworks_base/blob/master/core/java/android/view/View.java, and the formatted resulthttp://developer.android.com/reference/android/view/View.htmlAt 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.

author: Unknown
author_rank: Unknown
timestamp: January 07, 2014, 06:23:57 pm
content: 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.

author: AlfBaz
author_rank: Super Contributor
timestamp: January 07, 2014, 09:48:46 pm
content: Quote from: zapta on January 07, 2014, 05:14:34 pmBoth 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 andeverythingyou 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

author: rollatorwieltje
author_rank: Unknown
timestamp: January 07, 2014, 10:28:58 pm
content: 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.

author: fagiano
author_rank: Regular Contributor
timestamp: January 13, 2014, 06:26:40 pm
content: 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 centsciaoAlberto

author: zapta
author_rank: Super Contributor
timestamp: February 11, 2014, 03:30:15 am
content: Quote from: jucole on January 07, 2014, 06:23:57 pmWill 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.

author: westfw
author_rank: Super Contributor
timestamp: February 11, 2014, 10:24:01 am
content: 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.

author: T3sl4co1l
author_rank: Super Contributor
timestamp: February 11, 2014, 12:14:00 pm
content: 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