8

This may be a simple thing but in VB2010 I like to place my sources in the routine comments. Some URLs have embedded ampersands and this gets marked as a warning by the IDE.

''' <summary>
''' routine that creates a new file based on a definition query.
''' </summary>
''' <param name="newLoc"></param>
''' <returns></returns>
''' <remarks>
''' http://forums.esri.com/Thread.asp?c=93&f=992&t=194920#580036
''' http://forums.esri.com/Thread.asp?c=93&f=992&t=155005#452664
''' </remarks>
Public Function DoSelectLoc(ByVal newLoc As NewLocation) As Boolean
   'my routine
End Function

The two URLs above get marked with a warning. I've tried several alternate ways to write the URL but none have worked. I've tried the HTML code &#38; but that still has the ampersand. I know the IDE uses XML for the comments but there must be some way to write the URL without getting the warning and still keeping the same referenced link.

Update: Based on the discussion here http://social.msdn.microsoft.com/Forums/en-US/f14e7b55-c352-4ca5-a82c-bca3b83818db/double-ampersand-in-a-code-comment-causes-intellisense-error I decided to use the CDDATA to encapsulate my URLs like so:

''' <remarks>
''' <![CDATA[
''' http://forums.esri.com/Thread.asp?c=93&f=992&t=194920#580036
''' http://forums.esri.com/Thread.asp?c=93&f=992&t=155005#452664
''' ]]>
''' </remarks>

Seems to work to allow the links to work properly and also to not trip the Visual Studio warning.

sinDizzy
  • 1,300
  • 7
  • 28
  • 60
  • Martin Honnen's answer addresses the problem perfectly. But just want to clarify that the reason for the warning you refer (with no influence in the execution, anyway) is because of the XML structure of the Summary-type comments (http://msdn.microsoft.com/en-us/magazine/dd722812.aspx). You can use ampersands without any problem inside "conventional comments" (headed by a single '). The urls might be highlighted (if the corresponding text-editor option is enabled), although this fact will not have any effect (not even a warning). – varocarbas Nov 05 '13 at 18:22
  • yeah tried it initially with a single quote comment but wanted to upgrade to a better method. tried the & and it breaks the link. – sinDizzy Nov 05 '13 at 20:35
  • What did you expect? The url does not have &. You have to choose: if you want comments, you can put anything you want there (the urls would be fully-functional and might even work as links); if you want XML structure, you have to respect the XML requirements and, eventually, escape/replace some characters. Bear in mind that this has nothing to do with VB or VS, but with the XML language. – varocarbas Nov 05 '13 at 20:40
  • Although perhaps there are alternatives (not too expert on XML): http://stackoverflow.com/questions/6519457/ampersand-problem-in-xml-when-creating-a-url-string In any case have this idea clear: you should focus your research on XML, not on VB/VS comments. – varocarbas Nov 05 '13 at 20:55
  • yes I completely understand its XML. Yes I understand the limitations or rather the rules involved with XML. What I wanted to do was document my URLs and have them functional and also not trip the warning. It also seems that if I do this then the comments will get ignored by Visual Studio. I assume this is to render the documentation for the routines. – sinDizzy Nov 05 '13 at 21:09
  • looking in an MS forum on a related issue I came up with a reasonable workaround. put it in the original thread. – sinDizzy Nov 05 '13 at 21:14
  • Ah curious. I didn't know that CData was recognised by XML. Good to know. You can post it as the answer, if you wish. – varocarbas Nov 05 '13 at 21:20
  • 1
    Thanks. Its all part of a good discussion. That has bugged me for the last year. Glad I found something. – sinDizzy Nov 05 '13 at 21:25

2 Answers2

8

The right XML syntax is &amp; i.e. 

''' <remarks>
''' http://forums.esri.com/Thread.asp?c=93&amp;f=992&amp;t=194920#580036
''' http://forums.esri.com/Thread.asp?c=93&amp;f=992&amp;t=155005#452664
''' </remarks>
Martin Honnen
  • 160,499
  • 6
  • 90
  • 110
  • 1
    ok i tried this but the link becomes broken. in other words when i click on the link the website responds with an unknown thread id. if i leave the ampersand as-is the thread opens up no problem. – sinDizzy Nov 05 '13 at 19:27
7

Based on the discussion here I decided to use the CDATA to encapsulate my URLs like so:

''' <remarks>
''' <![CDATA[
''' http://forums.esri.com/Thread.asp?c=93&f=992&t=194920#580036
''' http://forums.esri.com/Thread.asp?c=93&f=992&t=155005#452664
''' ]]>
''' </remarks>

Seems to work to allow the links to work properly and also to not trip the Visual Studio warning.

varocarbas
  • 12,354
  • 4
  • 26
  • 37
sinDizzy
  • 1,300
  • 7
  • 28
  • 60
  • I have added your whole solution to help (future) readers. Hope you don't mind. Feel free to change it completely (back to what it was, if you wish). – varocarbas Nov 05 '13 at 21:58