"Jeff Garland" <[EMAIL PROTECTED]> writes: >> Indeed. >> >> // This is the documentation >> // for the function declaration >> // below it >> // :bar: description of bar >> // :foo: description of bar >> // >> // RETURNS: zero if foo and bar are equal, >> // -1 if bar is less >> // >> // THROWS: my_exception when either string is empty >> // >> // MAINTAINER NOTES: Docs for the maintainer only >> // >> int f(std::string bar, std::string foo); >> >> is beautiful. I was writing my comments almost exactly like this >> before I ever thought about automated extraction. > > Not to be difficult, but sorry, I don't really like it as you wrote it. If > you uncapitalized the titles it would be much better -- all caps is really > distracting to me.
Fine; we can quibble over details, but they're irrelevant to my point. > I like the fact that there is no '@' syntax for > identifying a tag, but there's still a tag to identify the sections. Just as a human needs in order to quickly find the information she needs. > In the case of :bar:, if we didn't have the discussion context I'm > not sure it would be obvious what it meant. If you weren't writing automated documentation you would write "The bar parameter" or "Params:" ? Whatever, the details don't matter. We can agree later on documentation standards. Heck, if people really can't agree they can configure their own comment processors. >> > So I think to be 'against doxygen' on this point is to be >> > against practicality. >> >> No, it's to be against ugliness and unreadability for the people who >> actually look at the code. There's no reason you can't have >> practicality and beauty. > > I'll be first in line when a viable replacement appears. > In the meantime I'll use the available tools. Then you're first in line. Synopsis already available. Just decide on a readable comment format, write a little Python script that parses it, and plug it in. >> > So I think it's great that Synopsys will support different options, >> > but I suspect even with Synopsys sophisticated docs will use >> > tagging. >> >> Only if nobody implements something better. >> >> > See: http://synopsis.fresco.org/docs/Tutorial/comments.html >> >> What's your point? I know Synopsis supports the Javadoc convention >> OOTB. Doesn't make it a good thing. > > The point is that practical documentation extraction requires a > syntax. Like it or not, the javadoc conventions are widely used and > we shouldn't preclude them. Maybe. I certainly wouldn't want to require them, and I don't want people to assume it's the best we can do. -- Dave Abrahams Boost Consulting www.boost-consulting.com ------------------------------------------------------- SF email is sponsored by - The IT Product Guide Read honest & candid reviews on hundreds of IT Products from real users. Discover which products truly live up to the hype. Start reading now. http://ads.osdn.com/?ad_id=6595&alloc_id=14396&op=click _______________________________________________ Boost-docs mailing list [email protected] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
