Re:Improved Doxygen documentation and search for C++ projects
by jcranmer on Thursday January 03, 2019 @09:54PM
(#18821596)
Look at LLVM's doxygen, say, http://www.llvm.org/doxygen/classllvm_1_1MachineRegisterInfo.... You see how things like const, bool, and unsigned are all believed to be classes? Go further down, and you can find a definition of a global variable Reg, which is from a case where Doxygen managed to think that the arguments of a function a global variables.
That's just the stuff I have readily available; there's been several times where I tried to use Doxygen to figure something out, only to discover that it was horribly confused and worse than useless (since it looks like it can tell you the information, but it doesn't figure it out).
Re:Improved Doxygen documentation and search for C++ projects
by shaklee3 on Thursday January 03, 2019 @11:46PM
(#18822026)
I used doxygen for a Cuda project, and it had quite a hard time with it. Due to the syntax differences, it would spit out warnings or errors. Some could be ignored, and some couldn't. I believe it's gotten better over the last year, though.
There's nothing inherently wrong with the code Doxygen generates or with its C++ parser. I've worked on large projects using crazy Boost pre-processor macros and plenty of C++14 features and Doxygen handled it all fine.
IME the number one problem with Doxygen is that the people writing the doc comments do a poor job. It's garbage in, garbage out.
The Java documentation is great because the people who write it put in a ton of effort to actually explain how to use their API, with examples, hyperlinks to other modules, version information, compatibility issues, and everything else. They're not adding trivial @param and @return comments as an afterthought.
Unfortunately, a lot of Doxygen documentation seems to be the trivial kind that tells you "@param foo The integer parameter foo" but doesn't give any clue how to use the library, class, or method.