BUG in VB.NET XML comment engine?

[Ray Cassick \(Home\)]

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/

 

[Herfried K. Wagner [MVP]]

Ray,

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.

I have checked it in both, VB 2005 and VC# 2005. It seems that the problem
you describe does not exist in VC# 2005. I'll investigate and get back
later.

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.

In VC# 2005, at least in the August CTP, it actually works. However, AFAIS
IntelliSense for XML comments in VB 2005 is much better than in VC# 2005
.

 

[Ray Cassick \(Home\)]

Thanks very much.

I am getting around it now by simple using a list in the description of the
exception but I really don't like this. It doe snot look as clean when the
docs are generated. People tend to look more at the bolded exceptions than
the individual elements of the descriptions.

Let me know what you find.

 

[Herfried K. Wagner [MVP]]

I am getting around it now by simple using a list in the description of
the exception but I really don't like this. It doe snot look as clean when
the docs are generated. People tend to look more at the bolded exceptions
than the individual elements of the descriptions.

Personally I prefer one entry per exception type, and a list of reasons for
this exception in the description (see 'list' XML comment element).

 

[Herfried K. Wagner [MVP]]

Addendum:

I have talked to some other MVPs and the conclusion is that C#'s behavior is
wrong. My suggestion is to list the exception once and add a list to
represent the reasons for the exception to be thrown.

 

[Cor Ligthert [MVP]]

Herfried,

I have talked to some other MVPs and the conclusion is that C#'s behavior
is wrong. My suggestion is to list the exception once and add a list to
represent the reasons for the exception to be thrown.

May I assume that it were mainly not C# MVP's.

)

Cor

 

[Herfried K. Wagner [MVP]]

Cor,

May I assume that it were mainly not C# MVP's.

That's true, but I didn't find a single sample in the .NET Framework
documentation which lists one exception type more than once. Instead, the
conditions are concatenated by "or" or similar.

 

[Ray Cassick \(Home\)]

Thanks.

That is what I am doing now and will continue. I can get used to it, it just
makes maintenance a bit difficult because now I don't just have to reference
each comment to the code but also the contents of each comment.

 

[Jay B. Harlow [MVP - Outlook]]

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


|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/
|
|

 

[Kevin Downs]

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.

I would agree that the VB behaviour is probably more logical, but this does
not mean that C# is wrong...

According to the 'official' source (Ecma C# 2.0 spec, Annex E), "The
documentation generator checks that the given member exists and translates
member to the canonical element name in the documentation file."
There is no mention of additional validation

Also the specification states "The documentation generator must accept and
process any tag that is valid according to the rules of XML." This seems to
preclude behaviour which VB exhibits - comments should not be 'arbitarily'
ignored...

[Note: In the context of the specification, the compiler is the
'documentation generatator' because it generates the documentation comments
*xml* file; NDoc would be refered to as a 'documentation viewer'.]


NDoc is 'agnostic' towards the tags in that it will document whatever tags
it is passed, so it's behavior cannot be right or wrong in this context


regards,
Kevin

 

[Jay B. Harlow [MVP - Outlook]]

Kevin,

I would agree that the VB behaviour is probably more logical, but this
does not mean that C# is wrong...

I didn't say one is right & one is wrong, I stated one seems "correct"' and
one seems "incorrect", (NOTE the quotes & the word seems). In other words
its subjective! Is the glass half empty or half full?

According to the 'official' source (Ecma C# 2.0 spec, Annex E), Also the
specification states "The documentation generator must accept and

Ah! There's the rub!

We are quoting the C# spec in reference to VB!

Repeat after me: VB is *NOT* C#. ;-)

NOTE: The official VB spec is ambiguous also:

http://www.microsoft.com/downloads/...09-EAA4-44D7-8AF3-E14280403E6E&displaylang=en

I hope you realize I was pointing out that the VB & C# documentation are
both ambiguous about the matter. This ambiguity obviously does not prove or
disprove the matter either way.

If anything this question demonstrates how "standards" & "specs" are so
easily open to interpretation on ambiguous sections such as this.

NDoc is 'agnostic' towards the tags in that it will document whatever tags
it is passed, so it's behavior cannot be right or wrong in this context

Again half full or half empty. In relation to how VB behaves its "wrong", in
relation to how C# behaves it "right".

--
Hope this helps
Jay [MVP - Outlook]
..NET Application Architect, Enthusiast, & Evangelist
T.S. Bradley - http://www.tsbradley.net

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.

I would agree that the VB behaviour is probably more logical, but this
does not mean that C# is wrong...

According to the 'official' source (Ecma C# 2.0 spec, Annex E), "The
documentation generator checks that the given member exists and translates
member to the canonical element name in the documentation file."
There is no mention of additional validation

Also the specification states "The documentation generator must accept and
process any tag that is valid according to the rules of XML." This seems
to preclude behaviour which VB exhibits - comments should not be
'arbitarily' ignored...

[Note: In the context of the specification, the compiler is the
'documentation generatator' because it generates the documentation
comments *xml* file; NDoc would be refered to as a 'documentation
viewer'.]


NDoc is 'agnostic' towards the tags in that it will document whatever tags
it is passed, so it's behavior cannot be right or wrong in this context



regards,
Kevin

 

[Kevin Downs]

I didn't say one is right & one is wrong, I stated one seems "correct"'
and one seems "incorrect", (NOTE the quotes & the word seems). In other
words its subjective! Is the glass half empty or half full?

I agree whole-heartedly.

Ah! There's the rub!

We are quoting the C# spec in reference to VB!

Repeat after me: VB is *NOT* C#. ;-)

I didn't say it was... What I was trying to point out is that the VB
behaviour is specifically excluded by the C# spec; The C# team couldn't
introduce it without a breaking change...

I would note however that although VB is not C#, it is copying an already
established mechanism for the xml docs, so consistancy may have been
desirable

NOTE: The official VB spec is ambiguous also:

http://www.microsoft.com/downloads/...09-EAA4-44D7-8AF3-E14280403E6E&displaylang=en

I hope you realize I was pointing out that the VB & C# documentation are
both ambiguous about the matter. This ambiguity obviously does not prove
or disprove the matter either way.

I wouldn't say the C# spec is ambiguous
"The documentation generator must accept and process any tag that is valid
according to the rules of XML."

Not much room for ambiguity there! Even if the tag is semantically wrong, C#
must pass it


As I see it, the problem with the VB implementation is that, when a
"suspect" documentation tag is found, it ignores the *entire* comment block.
So if you do anything VB considers wrong, you get no documentation
whatsoever !

IMHO, a compiler warning for the problem tag, and ignoring that specific tag
only, would have been sufficient...



Kevin

 

[Jay B. Harlow [MVP - Outlook]]

Kevin,
| I didn't say it was... What I was trying to point out is that the VB
| behaviour is specifically excluded by the C# spec; The C# team couldn't
| introduce it without a breaking change...

I hope you agree with my point all along that the behaviour is no
specifically included by the C# spec either.

| Not much room for ambiguity there! Even if the tag is semantically wrong,
C#
| must pass it

Obviously we will need to agree to disagree.

--
Hope this helps
Jay [MVP - Outlook]
..NET Application Architect, Enthusiast, & Evangelist
T.S. Bradley - http://www.tsbradley.net


"Kevin Downs" <msnewsATNOSPAMkdownsDOTcom> wrote in message
|
| >> I would agree that the VB behaviour is probably more logical, but this
| >> does not mean that C# is wrong...
| > I didn't say one is right & one is wrong, I stated one seems "correct"'
| > and one seems "incorrect", (NOTE the quotes & the word seems). In other
| > words its subjective! Is the glass half empty or half full?
|
| I agree whole-heartedly.
|
| >
| >> According to the 'official' source (Ecma C# 2.0 spec, Annex E), Also
the
| >> specification states "The documentation generator must accept and
| > Ah! There's the rub!
| >
| > We are quoting the C# spec in reference to VB!
| >
| > Repeat after me: VB is *NOT* C#. ;-)
|
| I didn't say it was... What I was trying to point out is that the VB
| behaviour is specifically excluded by the C# spec; The C# team couldn't
| introduce it without a breaking change...
|
| I would note however that although VB is not C#, it is copying an already
| established mechanism for the xml docs, so consistancy may have been
| desirable
|
| > NOTE: The official VB spec is ambiguous also:
| >
| >
http://www.microsoft.com/downloads/...09-EAA4-44D7-8AF3-E14280403E6E&displaylang=en
| >
| > I hope you realize I was pointing out that the VB & C# documentation are
| > both ambiguous about the matter. This ambiguity obviously does not prove
| > or disprove the matter either way.
|
| I wouldn't say the C# spec is ambiguous
| "The documentation generator must accept and process any tag that is valid
| according to the rules of XML."
|
| Not much room for ambiguity there! Even if the tag is semantically wrong,
C#
| must pass it
|
|
| As I see it, the problem with the VB implementation is that, when a
| "suspect" documentation tag is found, it ignores the *entire* comment
block.
| So if you do anything VB considers wrong, you get no documentation
| whatsoever !
|
| IMHO, a compiler warning for the problem tag, and ignoring that specific
tag
| only, would have been sufficient...
|
|
|
| Kevin
|
|

 

[Ray Cassick \(Home\)]

Aren't 'standards' grand

Sorry, but I have spent the day wrestling with the standard 'SIP' protocol
and how it is interpreted by various people

Kevin,
| I didn't say it was... What I was trying to point out is that the VB
| behaviour is specifically excluded by the C# spec; The C# team couldn't
| introduce it without a breaking change...

I hope you agree with my point all along that the behaviour is no
specifically included by the C# spec either.

| Not much room for ambiguity there! Even if the tag is semantically
wrong,
C#
| must pass it

Obviously we will need to agree to disagree.

--
Hope this helps
Jay [MVP - Outlook]
.NET Application Architect, Enthusiast, & Evangelist
T.S. Bradley - http://www.tsbradley.net


"Kevin Downs" <msnewsATNOSPAMkdownsDOTcom> wrote in message
|
| >> I would agree that the VB behaviour is probably more logical, but
this
| >> does not mean that C# is wrong...
| > I didn't say one is right & one is wrong, I stated one seems
"correct"'
| > and one seems "incorrect", (NOTE the quotes & the word seems). In
other
| > words its subjective! Is the glass half empty or half full?
|
| I agree whole-heartedly.
|
| >
| >> According to the 'official' source (Ecma C# 2.0 spec, Annex E), Also
the
| >> specification states "The documentation generator must accept and
| > Ah! There's the rub!
| >
| > We are quoting the C# spec in reference to VB!
| >
| > Repeat after me: VB is *NOT* C#. ;-)
|
| I didn't say it was... What I was trying to point out is that the VB
| behaviour is specifically excluded by the C# spec; The C# team couldn't
| introduce it without a breaking change...
|
| I would note however that although VB is not C#, it is copying an
already
| established mechanism for the xml docs, so consistancy may have been
| desirable
|
| > NOTE: The official VB spec is ambiguous also:
| >
| >
http://www.microsoft.com/downloads/...09-EAA4-44D7-8AF3-E14280403E6E&displaylang=en
| >
| > I hope you realize I was pointing out that the VB & C# documentation
are
| > both ambiguous about the matter. This ambiguity obviously does not
prove
| > or disprove the matter either way.
|
| I wouldn't say the C# spec is ambiguous
| "The documentation generator must accept and process any tag that is
valid
| according to the rules of XML."
|
| Not much room for ambiguity there! Even if the tag is semantically
wrong,
C#
| must pass it
|
|
| As I see it, the problem with the VB implementation is that, when a
| "suspect" documentation tag is found, it ignores the *entire* comment
block.
| So if you do anything VB considers wrong, you get no documentation
| whatsoever !
|
| IMHO, a compiler warning for the problem tag, and ignoring that specific
tag
| only, would have been sufficient...
|
|
|
| Kevin
|
|