[Mono-docs-list] Re: [Mono-list] More documentation info

[A Rafael D Teixeira]

>From: "Jason Diamond" <jason@injektilo.org>
>To: <mono-list@ximian.com>, <mono-docs-list@ximian.com>
>Subject: Re: [Mono-list] More documentation info
>Date: Wed, 13 Mar 2002 06:58:13 -0800
>
> > Lines to extract will have to be marked by the "apostrophe followed by 
>an
> > underscore" character sequence as the first non-whitespace content in 
>that
> > line.
>
>Just out of curiosity, why did you choose "apostrophe followed by an
>underscore"?
>
>There's a sample macro that comes with VS.NET called VBDocComments. It adds
>XML comments to the current method automatically by using the IDE to parse
>the code so that it can add the appropriate param names, etc. It uses three
>apostrophes as the prefix. These comments can't be extracted by vbc yet but
>just I assumed that the three apostrophes prefix was going to be used by 
>vbc
>in the future since that would be consistent with the three slashes csc
>uses.
>
>But I don't write in VB so don't really care. :-)
>
>Jason

I think 3 apostrophes would be error-prone, because the IDE has toolbar 
buttons to comment/uncomment blocks and you can by mistake or just for some 
temporary reason comment a block containing an already commented block (a 
very common pattern in my dayly use I can say of VB and VB.NET).

If done twice you would end with unintended code/comments extracted as 
documentation.

BTW, If you block comment some code with documentation lines those will not 
be extracted, but that will happen with my solution, too, and is in truth 
the right thing to happen.

The reason for all that trouble is that VB does not have something like /* 
*/, so that block commenting is done by line commenting each line in the 
block. An VB developers are used to it.

That is why I proposed an very unlikely combination of the line-coment 
marker (the apostrophe) with the line-continuation marker (the underscore). 
Oh, yes, VB syntax is line oriented...


Rafael Teixeira
Brazilian Developer


_________________________________________________________________
Get your FREE download of MSN Explorer at http://explorer.msn.com/intl.asp.