I'm fixing few issues in Html Help Builder related to HTML comments and how they are imported into Html Help Builder. While I'm working with this I'm checking things in VB and C# and I have to say that VB manages embedded <see> tags a heck of a lot nicer than C#. .In VB what happens as you type a comment like this:

''' <summary>

''' The <see cref="HelpBuilderTestLib.HelpBuilderTestClass" >Text we see in Help File</see>

''' </summary>

''' <value></value>

''' <returns></returns>

''' <remarks></remarks>

Public Property TestProperty() As Integer

    Get

    End Get

    Set(ByVal value As Integer)

    End Set

End Property

I get Intellisense for the embedded type reference:

But maybe more importantly when I look at the help comment in Intellisense it's properly formatted to include the link content rather than the cref value. In VB the Intellisense looks like this:

Notice that the comment displays the content text rather than the cref class reference value. Contrast that to the XML comment displayed in CSharp:

Note that the C# editor doesn't expand out the content but just displays the cref code link. Now I suspect in many cases that's sufficient but in others maybe not so much - the right behavior seems to be to display the content not the cref.

Nevertheless the VB usage is considerably easier to work with not just because it's easier to find references but also because it generates the correct syntax for each of the items embedded. In some cases you need namespace references in others you don't - the VB Intellisense will do the ight thing and the XML Comment generation code will clean up the references to fully qualified type or member signatures.

I've been struggling in matching XML comments to Html Help Builder's commenting features. While Html Help Builder can do just fine with what .NET provides via XML comments for imports some formats going the other way don't work. XML Comments for example don't really have a good way to represent comment links that don't point a type/signature reference of some sort. In a help file I may link back to other content like say a getting started topic.

HelpBuilder supports arbitrary comments, not just comments that reference other classes, so a comment may point back at another topic and that really doesn't work all that well. So if I something like this:

/// <summary>

/// Test Method with a very long<see cref="_012333123">alternate topic text </see>.

/// <seealso>Class HelpBuilderTestClass</seealso>

/// </summary>

(where cref is another help file topic id)

C# simply doesn't display the comment and VB displays the cref instead of the alternate topic text both of which seem wrong to me. Admittedly XML comments weren't designed for this sort of data, but still a little consistency would go a long way - there's data there use it for crying out loud!

Frustrating. And don't get me started on the freaking CodeDom differences of VB and C# <shrug>...