XML Comment Screwed - Possibly a bug in VB??

[Siv]

Hi,

Just busily coding away and removed a procedure from my code and all of a
sudden an error came up miles away from the location of the piece of code I
removed and it relates to the XML comment inserted at the top of the
procedure.

I had this happen once before and I couldn't fathom why it was complaining,
the XML comment is like this:

''' <summary>
''' If the Bonds flag is set in the security record we have at least one
Bond & Floating Charge
''' This routine locates the bonds that are linked to the Security
Record and adds them as sub nodes to
''' the main Bonds node.
''' </summary>
''' <param name="ParentNode"></param>
''' <remarks></remarks>

This gives an error:

"Warning 1 XML documentation parse error: Whitespace is not allowed at this
location. XML comment will be ignored. "

I then discovered if I remove the "&" ampersand symbol the error message
goes away???

Is this a "by design" thing or is this a bug in the XML comments??

Siv

 

[Stephany Young]

1. It's NOT an error - It is a warning!
They are totally different things.

2. & is the escape character in XML.
If you wish to include an & in XML then you need
to specify it as &amp;

 

[Michel Posseth [MCP]]

Well in fact it is an error Stephany ,, but not an error of the system
but an error of the person who wrote the comment
as XML follows the same rules as HTML for special characters , it seems that
this person wasn`t aware of this fact
the systems just warns that the XML doc will be broken


regards
michel

 

[Stephany Young]

Yes, certainly the user made an error, but the point is that VS reported a
warning and not an error.

 

[Siv]

Hi,
Ok "Warning" I must be more precise. However, I think when I am entering a
comment in my code and it "warns" me that "whitespace is not allowed at this
location .." when in fact it should say "Ampersand not allowed in VB
comment" it's more like a bug in VB as it is not telling me the true reason
for the error.

Your response assumes I understand XML which I never use, and have never
really understood why everyone raves about it? It just seems a bit insecure
as a method of holding or transmitting data as it's just plain text that can
be intercepted and read as such. I get the interactivity between systems as
a common data language, but you can achieve the same thing with a flat
file??

Siv

 

[Michel Posseth [MCP]]

Well some people have the option on in the ide that Warning=error ( just
for the simple fact that a warning then blocks a built until you solved the
issue )
so maybe he wasn`t aware

I guess that a lot of coders are not aware of the fact that the
documentation is in fact true XML that has a use on its own and can even be
used in externall reporting and tracking tools such as Ghostdoc , Sandcastle
etc etc etc

regards

Michel

 

[Stephany Young]

Again, by your own words, earlier you were insering an XML comment, so
saying that you didn't know it was XML just doessn't cut it.

It told you the exact reason for the warning, viz. whitespace not allowed at
that location. You had a space character directly following an & character
and that is not allowed in XML.

The use of XML comments, reasonably, expects the author to be able to write
wel-formaed XML. If you are not comfortable with XML then don't use XML
comments.

 

[Stephany Young]

Ignorance is no excuse.

Well some people have the option on in the ide that Warning=error ( just
for the simple fact that a warning then blocks a built until you solved
the issue )
so maybe he wasn`t aware

I guess that a lot of coders are not aware of the fact that the
documentation is in fact true XML that has a use on its own and can even
be used in externall reporting and tracking tools such as Ghostdoc ,
Sandcastle etc etc etc

regards

Michel

 

[Siv]

Stephany,
I didn't say I didn't know it was XML I said I didn't "understand" it. I am
aware that the the comments system used by VB.NET uses XML but that doesn't
mean I understand its internal working. You seem to be indicating that I
should? I am aware that my car uses an internal combustion engine but I
wouldn't dare mess with its internal workings or know everything about how
it works. I feel the same about comments. I have always used comments as a
way of letting others (or indeed myself when returning to code I haven't
worked on in a long time), know how a procedure works and any assumptions
that I have made when processing through it.

Using XML in comments was forced on me by MS when they designed the new
commenting system, and don't get me wrong, I like the fact that when I start
to type a call to the commented procedure it starts to tell me the meanings
of the parameters etc. To me this is just a bit of internal working of
VB.NET, not something I can manipulate other than by using its advertised
mechanisms. I have yet to fathom out how I turn these comments into
documentation for my project which I am sure I can do, but have so far been
totally unable to find out how??

To me there is a bug in the parser if it tells a (non XML understanding) VB
user that there is a problem with whitespace in the comment when in fact
it's a problem with you having inserted an ampersand??

Siv

 

[Siv]

Stephany,

That may be true, I wasn't looking for excuses, like most VB'ers who come
here we are looking for answers to problems that we can't resolve ourselves.
I didn't come here to be scolded for not understanding the internal workings
of XML. I came here to post what I thought was a bug (and still do
actually) in the VB parser. I also posted it because in finding that when I
removed the ampersand the issue went away. My hope being that if another VB
user like me who doesn't know why this "warning" comes up and doesn't know
how to get past it will read my post (and your replies subsequently) and get
a resolution to the problem. I also hoped that one of the developers from
Microsoft may become aware of it and perhaps tighten up the warning messages
so that the warning message can be a bit more focused on what is really
upsetting it.

The responses you give or rather the way that you deliver them, seem to be a
bit patronising. People should not be discouraged from asking questions here
even if to an experienced Guru like you they are child like. If all you are
about is showing off how clever you are at the expense of other users who
may not know as much as you, then you really shouldn't be here! Your
responses remind me of the Linux forums a few years back where newbies were
roasted for not knowing the internal working of BASH or some other esoteric
Unix command line switch.

Siv

 

[Stephany Young]

The whoule point is that youre not writing a comment.

You are writing an XML comment and there is a big difference.

A comment is all the text, on a line, that follows a single '

An XML comment is a block of text where each line starts ith ''' (3) and
otherwise contains well-formed XML.

If all you want to do is have readable comments in your code then just use
comments.

If you want to produce documentation, using the built-in mechanism, or
provide intellisense then you need to use XML comments and to use them you
MUST follow the syntax rules.

It is your choice, but don't blame the product when your syntax is not
correct.

 

[Göran Andersson]

Hi,
Ok "Warning" I must be more precise. However, I think when I am entering
a comment in my code and it "warns" me that "whitespace is not allowed
at this location .." when in fact it should say "Ampersand not allowed
in VB comment" it's more like a bug in VB as it is not telling me the
true reason for the error.

Actually, the compiler is telling you the exact reason for the error.
What you probably wish for is a message that tells you what it really is
that you are trying to do and how to do it, but that is impossible as
the compiler can not guess what is on your mind.

An ampersand is certainly allowed in an XML comment, but it has a
special meaning. It's used to specify characters otherwise impossible to
enter into XML code, so it should be followed by an identifier and a
semicolon, like &amp; or &lt;.

When you put an ampersand in the XML comment, the compiler expects it to
be followed by an identifier, by instead you put a space character after
it. In light of that, I hope that you see that the compiler message is
perfectly logical.



If you think that todays error messages are not informative enough, you
weren't around when they looked like this:

ERROR 47 IN LINE 460

Your response assumes I understand XML which I never use,

Obviously you do.

and have never
really understood why everyone raves about it?

It's main advantage is actually that everyone raves about it. It's a
widely spread format that is easy to read, both manually and
programattically. There is nothing magical about it, it's just simple
and structured, which is exactly what we need for a lot of the data
exchange nowadays.

For example, I can just point someone to an url where the can get an XML
file, perhaps accompanied by a short description if there is something
in it that is unexpected or unusal, and the person can easily look at
the file and determine how to write a program to read it. I don't have
to send along a 42 page documentation of the file format, including what
byte order and encoding to use, a description of the file structure, and
how every single piece of information is arranged.

It just seems a bit
insecure as a method of holding or transmitting data as it's just plain
text that can be intercepted and read as such.

If you want security, you should encrypt the data anyway. Protection by
obstruction just offers a false sense of security, not much more.

I get the interactivity
between systems as a common data language, but you can achieve the same
thing with a flat file??

Yes, of course you can, but XML offers a standardised and structured way
of doing that. Of course, it's a very bloated format, so there are still
some things that you want to use binary files for. For example, it would
not make sense to have a file with 10 million lines like this:

<pixel x="42" y="18" red="242" green="72" blue="0"/>

 

[Siv]

Göran
Thanks for the clarification, as I said to Stephany I am not experienced in
XML and certainly don't feel like I need to know it inside out to make
comments in my code. It does help to know why you get this type of error.

I have been programming in VB since Version 1.0 and prior to that have used
the likes of DBA, Clipper, C and so on. My first computer was a Sinclair
ZX81 followed by a Spectrum, then a QL, then an Atari 520ST and eventually a
PC where my coding started to get a bit more serious. I also worked on
Unisys B Series kit that had a Unix like OS and that treated me to some
interesting error codes similar to the one you mentioned when I was doing
some early forays into Pascal on that box. So I have seen around for a
while.

Siv

 

[Siv]

Göran,

Oh and on reflection, I actually preferred "ERROR 47 IN LINE 460" as it
saves you time. Today when I get an error in VB.NET I have to go to the red
Exclamation to get the initial error box, then I have to click another link
to get the detail, then I have to scroll down to the line that tells me
which line or lines threw the error. This usually involves messing about
expanding the text box to see the last entry on the line which is the actual
line number where the error occurred. I am sure that I am missing loads of
really useful information in the reams of .NET error messages, but to be
honest all I really need is what the error is and on which line in my code.

I like .NET programming, but I think sometimes the VB developers have lost
site of what Visual Basic was all about. It is an easy to use programming
language for people like me who want to put together applications quickly
that access databases and produce reports without bogging the programmer
down too deeply in what is really going on under the hood.

I don't care what language you program in, if your not actually writing
machine code, you are not _really_ understanding what is going on under the
hood. I am constantly peeved by this rubbish people write about how C++ is
a real Man's programming language and VB is for kids. To me all programming
languages and IDEs are a tool to achieve an end. That being to produce
programs that end users can use to do their work. VB has always been a tool
that did that with minimum fuss and the guys that wrote it shielded us from
some of the more serious stuff that was really going on under the hood.

It is a balance, I want to have as much control over the things that I want
to do as is necessary, without getting bogged down in computer science.

Siv

 

[Herfried K. Wagner [MVP]]

as XML follows the same rules as HTML for special characters

This is not entirely correct, but basically you are right -- certain
characters must be "escaped".

 

[Michel Posseth [MCP]]

Siv ,,,

Don`t get upset about postings in the groups ,, some people over here are
indeed a bit rude in there answering
this may have several reassons .

1. The person asnwering is really a sociopath
http://wiki.answers.com/Q/How_do_you_know_if_someone_is_a_sociopath

2. The person answering lives in a european country wich is competing in
the EK soccer and he / she is not wearring orange at this moment
especially Italian and French people are a bit tricky at the moment
;-)
http://en.wikipedia.org/wiki/Netherlands_national_football_team ( scroll
to the 2008 section below )

3. The person answering might not have his / her day ,,,,, most of the times
a look at other postings of this person at this day and other days is enough
to know if this is true .

4. Not all persons in this group ( me for instance ) are native English
speakers , so remember that sometimes the postings are interpreted in a
different way as they were intended.

If you are a bit longer active in this groups you will know them bether ,
and you will see that we are all humans here and most of the times only
option 2, 3 or 4 apply . Ocassionally we have a option 1 but i can ensure
you that those people are a long time not seen here .



regards

Michel Posseth

 

[Siv]

Michael,

I am quite "thick skinned" so it didn't bother me too much. I know I am not
the most knowledgeable person on VB.NET as I only use the bits of the system
that work for me in getting the job done. I don't have a lot of time to get
to really know the product to the level that you guys do, even though I have
been using VB since version 1.

I am a self employed developer and keep promising myself that when I have
built up some spare funds I should get on a course that teaches me the full
working of the Visual Studio IDE and a deeper understanding of VB and the
..NET framework as I am sure I am not getting the best out of it.

I just wanted to make Stephany aware that her style of response seems very
unwelcoming and her tone unnecessarily superior. I have always found that
these newsgroups are generally a friendly and welcoming place where
developers can get help and advice from their peers without fear of being
scolded for not knowing something that an expert feels they should know. I
would love to spend months playing with Visual Studio and getting to know
every aspect of it, but I have to earn a living and that stops me from doing
that.

Thanks for taking the time to respond to this as it's nice to know that some
experts do care about those who come here looking for help.

Siv

 

[Siv]

Michel,

I am quite "thick skinned" so it didn't bother me too much. I know I am not
the most knowledgeable person on VB.NET as I only use the bits of the system
that work for me in getting the job done. I don't have a lot of time to get
to really know the product to the level that you guys do, even though I have
been using VB since version 1.

I am a self employed developer and keep promising myself that when I have
built up some spare funds I should get on a course that teaches me the full
working of the Visual Studio IDE and a deeper understanding of VB and the
..NET framework as I am sure I am not getting the best out of it.

I just wanted to make Stephany aware that her style of response seems very
unwelcoming and her tone unnecessarily superior. I have always found that
these newsgroups are generally a friendly and welcoming place where
developers can get help and advice from their peers without fear of being
scolded for not knowing something that an expert feels they should know. I
would love to spend months playing with Visual Studio and getting to know
every aspect of it, but I have to earn a living and that stops me from doing
that.

Thanks for taking the time to respond to this as it's nice to know that some
experts do care about those who come here looking for help.

Siv