Links in Visual Basic

Mar 3, 2008 at 1:53 AM
I've successfully converted a lot of XML documentation in C# code that was originally developed for Visual Studio 2003 and NDoc to work with Visual Studio 2005 and Sandcastle with Sandcastle Help File Builder. Now I'm trying to do the same with some XML documentation in Visual Basic code. The <see/> tags that I have converted to reference overloads by following the instructions in the Linking to Overloads thread http://www.codeplex.com/Sandcastle/Thread/View.aspx?ThreadId=22348&ANCHOR#Post74806 are working fine. But all the other <see> tags, which worked fine in NDoc, generate broken links in Sandcastle. I've tried a few variations to no avail.

If there's a special trick to getting the references in <see/> tags in Visual Basic to work with Sandcastle, I would like to know what it is.
Mar 3, 2008 at 2:37 AM
Edited Mar 3, 2008 at 2:39 AM
Hi,

Check the XML file that the compiler creates for <see/> elements that aren't working in Sandcastle. If the cref appears valid, then maybe you could post some examples. If they don't appear valid, then the problem is with the syntax you're using in your comments. Again, posting a few examples may help.

- Dave
Editor
Mar 3, 2008 at 2:52 AM
The VB.NET compiler doesn't always generate fully qualified names in cref attributes. It's got a bad habit of just outputting what you specify rather than a fully qualified member name with an appropriate prefix. The only known workaround is to fully qualify the name and include the prefix in your comments (T: for type, M: for member, P: for property, etc). For example:

''' See the <see cref="M:MyClass.MyMember(System.Int32)"/> method.
''' See the <see cref="P:MyClass.MyProperty" /> property.

Eric
Mar 4, 2008 at 12:39 AM
Hello Dave and Eric,

Eric's instructions worked fine with the addition of a couple of oddities. A few links still did not work after following Eric's instructions. I figured out the exceptions by comparing the <see/> tags in the XML file with the headings for the corresponding referenced members in the same XML file. In each case where I had a broken link, the reference in the <see/> tag did not exactly match the heading of the referenced member. From this investigation, I worked out two additional instructions.

1. If a referenced method contains a reference parameter (ByRef in VB), "@" must be appended to the parameter's type. For example :

''' See the <see cref="M:MyNamespace.MyClass.MyMethod(System.Object@)"/> method.
2. If a referenced method contains no parameters, closing parentheses must not be appended to the method name. For example :

''' See the <see cref="M:MyNamespace.MyClass.MyMethod"/> method.
Thank you both once again for your help.

Simon
May 2, 2008 at 1:01 PM
I seem to have this issue, I haven't been able to find any sort of workaround. It is particularly difficult because I have a huge number of methods with some complex signatures.

Whilst I can find out how these need to be linked to from the Reflection.XML file I seem to be in the position where VB.Net never outputs any <see cref properly.

The following:

''' <remarks>
''' <list type="bullet">
''' <item>Link1: <see cref="M:SandTest.Base.GenericRequest.Link1(SandTest.Base.eCannotProcessReason@)"/></item>
''' <item>Link2: <see cref="M:SandTest.Base.GenericRequest.Link2(System.String@)"/></item>
''' <item>Link3: <see cref="M:SandTest.Base.GenericRequest.Link3"/></item>
'''</list>
''' None of these seem to generate viable XML :-(
'''
''' <see cref="Link3"/>
''' <see cref="GenericRequest.Link3"/>
''' <see cref="Base.GenericRequest.Link3"/>
''' <see cref="SandTest.Base.GenericRequest.Link3"/>
''' <see cref="eCannotProcessReason"/>
''' <see cref="eCannotProcessReason.AllOk"/>
'''
''' <see cref="AcceptRejectRule"/>
'''
''' </remarks>

Produces:

<remarks>
<list type="bullet">
<item>Link1: <see cref="M:SandTest.Base.GenericRequest.Link1(SandTest.Base.eCannotProcessReason@)"/></item>
<item>Link2: <see cref="M:SandTest.Base.GenericRequest.Link2(System.String@)"/></item>
<item>Link3: <see cref="M:SandTest.Base.GenericRequest.Link3"/></item>
</list>
None of these seem to generate viable XML :-(

<see cref="Link3"/>
<see cref="GenericRequest.Link3"/>
<see cref="Base.GenericRequest.Link3"/>
<see cref="SandTest.Base.GenericRequest.Link3"/>
<see cref="eCannotProcessReason"/>
<see cref="eCannotProcessReason.AllOk"/>
<see cref="AcceptRejectRule"/>
</remarks>

All descriptions I have been able to find seem to suggest that sometimes it fails to output a properly formatted tag, in my case it seem to never output a properly formatted tag.

Does anybody have any further suggestions ?

Thanks,

Simon.
May 2, 2008 at 3:22 PM
Hi Simon,

Out of curiosity, what version of Visual Studio are you using? I'm wondering if this issue was fixed in VS 2005 SP1 or at least VS 2008.

I found this discussion, which indicates that it's a possibility:

http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=802863&SiteID=1

Someone submitted a bug report to Microsoft about this problem a while ago. It appears that the issue was deferred to VS 2008, but I have not seen any confirmation that it works now.

https://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=219950&wa=wsignin1.0

If it still doesn't work in VS 2008, you should submit a new bug report to the Microsoft Connect website.

- Dave
May 2, 2008 at 3:37 PM
Hi Dave,

I'm on VS2005 SP1. From what I've read in the various posts I've found it seems as though SP1 was the start of the problem. I'm not going to be moving to VS2008 anytime soon and don't have it available at the moment to investigate.

I was just (optimistically) hoping that maybe somebody had come up with a magical solution.

Simon.
May 26, 2008 at 11:05 PM
Hello Dave and the new Simon,

I see two Simons are now participating in the thread.  I'm also on VS2005 SP1 with no plans to upgrade to VS2008 any time soon.  I did not reply earlier because I've been out of the office for a few weeks.

The original Simon
May 29, 2008 at 7:09 PM
Yes the odd VB behavior with crefs was invented in VS2005SP1. It was somehow repaired in VS2008 but many crefs are still broken or target to unpredicable targets. I've read (not tested) that in VS2005SP1 you can workaround this by running vbc from command line.
I really dislike the way how VB team treats XML comments :-(.