"Jeff Garland" <[EMAIL PROTECTED]> writes:
> 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.
?? Why? I could write it in about 10 minutes.
> 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.
And the consistency needed for humans is enough for automated
extraction.
>> 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....
They won't want a "tag" if that's not the way the system works.
They'll want an extension to the doc format. Probably just the
recognized section labels if we're going with
LABEL: whatever
etc.
or
Label: whatever
etc.
>> > 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 ;)
You already know Python. You just don't know you know it ;-)
--
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
