On Sat, 26 Mar 2005 13:30:06 -0500, David Abrahams wrote > > 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:" ?
I'd probably write something like: // bar -- description here // foo -- description here But that's a really high bar for the documentation parser. Also, something like this does have the advantage that I can easily scan for the parmeter descriptions in a longer comment. // Parm: bar -- description here // Parm: foo -- description here Of course the more we talk about this, the more I see your objections to the tag approach :-) Good use of whitespace and formatting is important to readability and the tag systems certainly intrude on that. > 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. I think it's clear that in the general case there will always be someone that wants some new added tag for some special purpose documentation structuring. It comes up over and over.... > > 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. Let me rephrase -- I'm in the line that doesn't require me to write a parser script in a language I don't know ;) > > 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. Agree to both. Jeff ------------------------------------------------------- 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
