On Tuesday, February 04, 2003 7:24 AM [GMT+1=CET], Jeff Garland <[EMAIL PROTECTED]> wrote:
> > Hey, I'd like to step back and strategize, here. I was going to > > start > > making Synopsis generate BoostBook, but I don't want to invest the > > time if Doxygen is going to "Just Work". Well, I might, just > > because > > I don't want to write crufty Doxygen comments, but I really > > shouldn't. > > Yes, I recall a discussion about this in the past ;-) Refresh my > memory on how synopsis can tell the difference between a comment > intended as a description of a return value of a function > as opposed to a description of the function without some > sort of text to distinguish one from the other? Or is it > just that the syntax has less cruft? Synopsis has tunable comment processors - you can make them as smart or as dumb as you want them to be (it's Python, so it's easy ;-)). In my case, the rule is simple - the comment describing the function appears as a solid block right before its declaration with no intervening line separation. > > > So, my question is this: has Doxygen finally become a robust > > parser/comprehender of C++, or is there still good reason to pursue > > Synopsis? > > I wish this was going to be an easy answer ;-) > > FWIW, the Doxygen parser has recently been rewritten. For all I > know, though, this might make it more unstable. Anyway, I'm sure > there are still some flaws and I think that Meta-programs will > be the likely place you will find them since Doxygen tends to > be utilized mostly by C++ projects writing more traditional C++. > Also, since the XML output is still experimental (and according to > Doug's work broken in recent releases) we might need to take that > into account as well. > > All that said, for date_time it looks like it is going to do the > job nicely. My best guess is that for MPL (and friends) things > will still be a bit dicey with Doxygen... OK. > > Conversely, If Doxygen is going to fail us eventually, > > maybe Jeff and I should put our efforts into Synopsis. I have got > > Synoposis to parse all of Boost.Python and it does a good job of > > understanding everything, including some difficult metaprogramming > > constructs. > > That's good to hear. It doesn't look like Synopsis has an > XML ouptput formatter yet -- is that in the works? It has a DocBook formatter, in fact... though it's being a little bit strange about type qualifiers at the moment. We just need to take a look at the differences with the HTML formatter to see what the major differences are. > Also, as I recall > last time I checked on Synopsis I had installation issues or some > other difficulty -- that would have been shortly after the last > committee meeting. I think I can help with that. Anyway, since I've just wiped my machine I'm going to want to reinstall it myself, so we can experience the joys together ;-) > > Incidentally, Jeff, Synopsis can recognize Doxygen comments and > > can emulate its output format if you want, so it wouldn't > > be a waste for you. > > Right, thanks for reminding me of that. > > > I just don't want to duplicate our efforts unneccessarily. > > Agreed, but I think in this case the diversity might be ok. > Document generation is sufficiently complex that I'm sure that > Synopsis and Doxygen will continue to have various strengths and > weaknesses that might draw some users to one or the other solution. They might, but as Doug has pointed out repeatedly, you won't be able to simply process regular C++ code and get reasonable BoostBook, so we'll have to add some new directives, markup formats, etc. That will be repeated work for us, on top of whatever differences the two tools have. I also think it's very likely that Synopsis will be an easier framework for that kind of project, due to its modular structure and the fact that it's written in Python... but I could be wrong about that. Haven't looked at Doxygen's code recently. -Dave ------------------------------------------------------- This SF.NET email is sponsored by: SourceForge Enterprise Edition + IBM + LinuxWorld = Something 2 See! http://www.vasoftware.com _______________________________________________ Boost-docs mailing list [EMAIL PROTECTED] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
