Re: [boost] [documentation] help - SFINAE confuses doxygen

Subject: Re: [boost] [documentation] help - SFINAE confuses doxygen
From: Simonson, Lucanus J (lucanus.j.simonson_at_[hidden])
Date: 2009-02-23 12:24:37

>> Simonson, Lucanus J wrote: 
>>> 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. 

> on Sun Feb 22 2009, Stefan Seefeld <seefeld-AT-sympatico.ca> 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.
> 
David Abrahams 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.

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