Re: [Boost-docs] [quickbook] Comments

Subject: Re: [Boost-docs] [quickbook] Comments
From: Kai Brüning (kai_at_[hidden])
Date: 2007-07-30 15:04:08

Joel de Guzman wrote:
>Kai Brüning wrote:
>
>>> [/ this is a quickbook comment /]
>>>
>>> I think this is the best suggestion so far. However, it is, again,
>>> breaking.
>>>
>>> Anyway, now that we are talking about breaking code for 1.4 (or 1.5 as John
>>> suggests), perhaps it's time to implement it this way?
>>
>> One additional aspect: Nestable comments can't be catched by a single regular
>> expression.
>>
>> I am currently implementing syntax hiliting of quickbook files for the
>> Pygments syntax highlighter. Using regular expressions and states, the
>> nestable comments in 1.4 forces a lot more states because comments can be
>> nearly everywhere.
>>
>> I wouldn't rate this important, but everything else being equal, the easier
>> handling of non-nestable comments with regular expressions may be of value in
>> a variety of cases.
>
>Indeed! This was one of the the reasoning that Rene (and Dave) had
>when that comment syntax was suggested. So, could you please state
>if you are in favor of the [/ this is a quickbook comment /] syntax
>for 1.5 and above?

Let me first say that I haven't used quickbook yet. I am just working on the syntax hiliting.

That said, in C++ I heavily use /**/-comments to disable code temporarily. Therefore I'd always vote for a comment syntax which is at least undisturbed by the "normal" syntax of the language, as the [/ style /] would be. For my use in C++ at least even nestability of comments would be a big plus, but maybe this isn't so important for quickbook because "normal" (not used for disabling) comments are probably less frequent than in C++.

Considering it all together, non-nesting [/ /] scores most points for me. An additional plus over the original [/ ] syntax is that it is closer to usual multiline-comment syntax with some kind of symmetric bracketing.

But again, I have no experience using quickbook.

Kai