CODEWITHSUNDEEP
c#vb.netvisual-studio-2010visual-studio
rory.ap
rory.ap

Reputation: 35328

Why isn't C# XML member documentation as "smart" as it is in VB.NET? Workarounds?

One thing I've noticed as I'm migrating from VB.NET to C# is that the XML documentation for members is not as "smart" in C# as it is in VB.NET. For one, it's lacking the intellisense when you're referencing other things. For example, in the screen shots below, I have methods where I'm trying to reference String in the documentation. With VB, I get the intellisense dropdown, and with C#, I don't.

enter image description here enter image description here

Secondly, if I change the name of an argument, it doesn't produce a warning in C# as it does in VB.NET indicating that the documentation no longer matches the method signature:

enter image description here enter image description here

This is particularly "dangerous" because it can lead to your API documentation being incorrect.

What accounts for these differences? Is there a good reason why C# is limited in this way? Or should I be looking at it differently or doing something in a different way?

Upvotes: 2

Views: 153

Answers (2)

Sourav 'Abhi' Mitra
Sourav 'Abhi' Mitra

Reputation: 2520

For the first part using Ghost Doc would be a good idea.

As for the second the XML Documentation file checkbox needs to be checked in your project settings. All missing/incorrect XML comments would turn up as warnings.

If you absolutely want to make sure none of the warnings escape into production turning on Treat warnings as errors would be a good idea.

Upvotes: 1

Hans Passant
Hans Passant

Reputation: 942468

You are just seeing a side-effect of the C# and VB.NET IDEs having been implemented by very different groups inside Microsoft. Small groups is a survival strategy for any software company, Microsoft is not an exception.

And there's history behind these efforts, Visual Basic had strong IDE support long before C# ever came around. The VB.NET team certainly got a running start on implementing theirs. That isn't always an advantage, they were also stuck with having to make it similar to earlier IDEs to lessen the adoption shock that their prior VB customers had to go through. Already a very significant one, VB.NET is pretty drastically different from earlier VB versions. And otherwise not different from the one you are experiencing right now.

And they ultimately have different goals. Very visible in your screenshot for example, the VB.NET IDE has the tabbed window with the "Common" and "All" tabs. That has gotten a lot of VB.NET programmers in trouble, never figuring out that they need "All" sometimes. C# doesn't have that, not the kind of language that ever aggressively hid anything.

We cannot help you paper over these differences, there are no settings for them. You can file a feature request at user voice but that's probably largely a waste of your effort. Prior requests to change IntelliSense have consistently been met with "Thanks, we'll consider it for our next version!" without them being implemented.

You'll get used to it, all C# programmers did.

Upvotes: 3

Related Questions