Ray,
In addition to the other comments:
IMHO the VB 2005 behavior seems "correct", while the C# & NDoc behavior
seems "incorrect". Unfortunately I don't see an "official" schema for XML
comments to know specifically which is truly correct. Looking at the
documentation is ambiguous at best.
VB XML documentation
http://msdn2.microsoft.com/ms172653(en-US,VS.80).aspx
C# XML documentation
http://msdn2.microsoft.com/b2s063f7(en-US,VS.80).aspx
| ''' <exception cref="ArgumentException">Will be thrown if the pageNumber
is
| less than zero.</exception>
| ''' <exception cref="ArgumentException">Will be thrown if the pageNumber
is
| greater than the number of pages contained in the collection.</exception>
You're "duplicating" the ArgumentException exception element, if you have
15, 20 or more exceptions, this could easily cause problems.
I could see allowing ArgumentException exception elements more then once if
there was also a "argument/param" attribute on it. Something like:
| ''' <exception cref="ArgumentException" paramref="pageNumber">Will be
thrown if the pageNumber is
| less than zero.</exception>
| ''' <exception cref="ArgumentException" paramref="pageSize">Will be thrown
if the pageSize is
| Size.Empty or doesn't contain positive values.</exception>
However in your example I would still expect a warning, as you have two
ArgumentExceptions that refer to pageNumber.
As Herfried suggests, I would use a single exception element with either
<para> or <list> to list the various reasons it may be thrown.
--
Hope this helps
Jay [MVP - Outlook]
..NET Application Architect, Enthusiast, & Evangelist
T.S. Bradley -
http://www.tsbradley.net
"Ray Cassick (Home)" <rcassickNOSPAM@enterprocity.com> wrote in message
news:uD%23xnfv8FHA.3200@TK2MSFTNGP11.phx.gbl...
|I have been using XML Comments in VB.NET during my time with VS.NET 2003
| thanks to VBXC and NDoc. I just started to upgrade one of my projects into
| VB.NET 2005 and am seeing some odd errors centered around my past use of
XML
| comments. I am interested to know if you all think this is a bug or
'working
| as designed' and I was just lucky to get away with it.
|
| I had a method that could, based upon two different cases throw an
| ArgumentException. I had commented it this way:
|
| ''' <summary>
| ''' Allows the caller to get the name of a wizard form with its index
| number.
| ''' </summary>
| ''' <param name="pageNumber">Integer value indicating the wizard page to
| reference.</param>
| ''' <returns>The name string of the wizard page at the referenced
| index.</returns>
| ''' <exception cref="ArgumentException">Will be thrown if the pageNumber
is
| less than zero.</exception>
| ''' <exception cref="ArgumentException">Will be thrown if the pageNumber
is
| greater than the number of pages contained in the collection.</exception>
|
| VS.NET 2005 now complains of the following:
|
| XML comment tag 'exception' appears with identical attributes more than
once
| in the same XML comment block. XML comment will be ignored.
|
| Seems to me this is a bug in the XML comments engine. NDoc creates a table
| showing each exception you can get and the reason why it would be thrown.
| This table allows (as does the NDoc schema apparently) for exceptions of
the
| same type but different reasons.
|
| Anyone here care to comment on their thoughts? I have not tried the same
| thing in C# so I am not sure if it would work differently there or not.
|
|
|
| --
| Raymond R Cassick
| CEO / CSA
| Enterprocity Inc.
|
www.enterprocity.com
| 3380 Sheridan Drive, #143
| Amherst, NY 14227
| V: 716-316-5973
| Blog:
http://spaces.msn.com/members/rcassick/
|
|
