[documentation] help - SFINAE confuses doxygen
I have noticed after attempting to document my overloaded template functions in doxygen that is simply doesn't work. Doxygen appears to consider all SFINAE overloads of a templated function as a single function, but doxygen's treatment of them is quite erratic. It seems to generally have a bunch of assumptions built into its internal logic about what can't happen in C++ code that aren't valid in my case. Does anyone have any suggestions for how to deal with these issues? I notice that doxygen is used with BoostBook, and I know this must have come up in other libraries. How is it solved? Thanks, Luke
AMDG Simonson, Lucanus J wrote:
I have noticed after attempting to document my overloaded template functions in doxygen that is simply doesn't work. Doxygen appears to consider all SFINAE overloads of a templated function as a single function, but doxygen's treatment of them is quite erratic. It seems to generally have a bunch of assumptions built into its internal logic about what can't happen in C++ code that aren't valid in my case. Does anyone have any suggestions for how to deal with these issues? I notice that doxygen is used with BoostBook, and I know this must have come up in other libraries. How is it solved?
I certainly haven't solved it. http://www.boost.org/doc/libs/1_38_0/doc/html/boost/units/pow_id3803587.html (e.g.) In Christ, Steven Watanabe
Steven Watanabe wrote:
It could be a problem in doxygen or with boost's doxygen2boostbook xsl transform. Try running doxygen over the code standalone (that is, outside of the boostbook toolchain). If the problem persists, you can try reporting the problem to the Doxygen team. If it doesn't, post a message to the boost docs list (mailto:boost-docs@lists.boost.org) and someone will fix it. In my experience, doxygen doesn't handle advanced C++ very well at all. I have sometimes had to resort to hand-editing doxygen's output, which pretty much defeats its purpose. -- Eric Niebler BoostPro Computing http://www.boostpro.com
Eric Niebler wrote:
Thanks Steven, Eric, I am using doxygen standalone for now. I've pretty much come to the conclusion that I have to treat doxygen as little more than an alternative to direct html editing because its extraction capabilities prove near useless to me. I figure I can define a doxygen \page for each overloaded function name, list the concepts/(combinations of concepts) that work with that function and let doxygen autolink to documentation on each concept struct that includes a list of function names that ought to link back to those pages since the real functions will remain "undocumented" as far as doxygen is concerned. If I throw the concepts in a group I ought to have a very nicely organized document. Doxygen can create nice html from the original source and I can link to the header files in which things are defined by header file name, but I haven't found a way to link to a tag within a source file allowing a reader to link directly to the declaration of a function, for instance. All this is only marginally better than achieving the same thing by hand in html. Even so I should have a very nice document in short order. I'm working on it full time, and plan on having it ready for review by April. Regards, Luke
Simonson, Lucanus J wrote:
Have you tried Synopsis (http://synopsis.fresco.org) ? David Abrahams tried it out a long time ago, as a result of which I applied many improvements. I still generate boost docs with it from time to time, but don't maintain official docs anywhere for it. I would be interested to help get things up and running again, if people find it useful. Thanks, Stefan -- ...ich hab' noch einen Koffer in Berlin...
on Sun Feb 22 2009, Stefan Seefeld <seefeld-AT-sympatico.ca> wrote:
Hello?!? I can't believe Synopsis hasn't caught on among Boosters who use Doxygen -- I get the sense that nobody but me has even really tried it. It's got a real C++ parser under the hood, and it uses Boost.Wave, which means it can do stuff that others can't. I mean, c'mon, we have the developer right here in our midst! If something goes wrong he can fix it. It even has a mode that groks doxygen comment syntax; it should be a near drop-in replacement. -- Dave Abrahams BoostPro Computing http://www.boostpro.com
David Abrahams wrote:
I was hoping to learn about an alternative to doxygen such as this from the list. I like that synopsis has a C++ API and is hackable. There are so many things (such as document extraction) that the compiler ought to be able to do the help developers in addition to producing syntax errors and warnings. I was thinking that with the new plugin architecture for gcc such things could be made gcc plugins, but any decent frontend would do. Every compiler comes with its own issues. I have to carefully handhold ICC, gcc and MSVC through compiling my code because they all have their shortcomings. I would need to carefully make sure that synopsis is able to successfully parse my code without producing spurious syntax errors in order to be able to use it. One problem with doxygen is that it is largely silent to error conditions during parsing, making it very hard to understand why it fails to produce sensible documentation, if any, for given code and associated markup. At any rate, I have some work ahead of me to evaluate the potential of synopsis and feel out any pitfalls it may have. Luke
David Abrahams wrote:
Indeed. But what's missing is what is usually missing... Someone to do the work do integrate it with the rest of the documentation chain and to make it "easy" for authors to use. But I see Simonson is starting to look into it.
I do have one question about that... Why is it that having Stefan in Boost is an advantage in this case but having Volodya, Jurko, Noel, myself, and others with respect to bjam/build vs. cmake isn't an advantage? -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org (msn) - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim,yahoo,skype,efnet,gmail
on Mon Feb 23 2009, Rene Rivera <grafikrobot-AT-gmail.com> wrote:
Of course having y'all here is a huge advantage for BB. Without you, continuing with BB would be untenable. -- Dave Abrahams BoostPro Computing http://www.boostpro.com
Stefan Seefeld wrote:
I wasn't able to get the build to work with boost dependencies. I have a 1.35 installation, setup confirmed that the version of boost was >=1.35 under the prefix I gave it, but failed immediately after with an error that it couldn't find boost.filesystem. I installed without boost dependencies and eventually figured out to set PYTHONPATH to point to lib/python2.3/site-packages under my installation directory, but am still not able to run it because it gives the error "no processor 'Cxx.Parser'" I tried setting LD_LIBRARY_PATH to point to lib/python2.3/site-packages, but that didn't seem to work. The README instructions said only to set these two variables to the "appropriate" values. I guess I need more help than that. Thanks, Luke
Note: I replied off-list, as this is off-topic here. Thanks, Stefan -- ...ich hab' noch einen Koffer in Berlin...
It looks very interesting (though I thought the layout shown was a bit thinly spread out). (Though I think we should not lose sight of the considerable advantages to be gained from using Doxygen even 'as is' either standalone or in autodoc mode with Quickbook . Things as trivial as a list of macros (commented of course) can save users a lot of hassle. But I agree it doesn't do all we want yet. We should also consider asking for improvements - Doxygen is being active maintained (as I discovered when I suggested (wrongly as it turned out) that some definitions might not be output). But a 'more tame' support would of course be even better ;-)
I would be interested to help get things up and running again, if people find it useful.
To let the Pythonly/Unixly challenged get a feel for what it will do on their pet project, posting a standalone Windows MSI would be a big help. Paul --- Paul A. Bristow Prizet Farmhouse Kendal, UK LA8 8AB +44 1539 561830, mobile +44 7714330204 pbristow@hetp.u-net.com
On Fri, Feb 20, 2009 at 7:20 AM, Simonson, Lucanus J <lucanus.j.simonson@intel.com> wrote:
Try the following: use \cond ... \endcond around code which you want Doxygen to ignore. Use #ifdef DOXYGEN_ONLY ... #endif around code formatted specially for Doxygen which you want the compiler to ignore. Tell Doxygen to predefine DOXYGEN_ONLY. Yechezkel Mett
participants (8)
-
David Abrahams -
Eric Niebler -
Paul A. Bristow -
Rene Rivera -
Simonson, Lucanus J -
Stefan Seefeld -
Steven Watanabe -
Yechezkel Mett