25

I use Microsoft Visual Studio 2012. When I put code examples into XML comments of C# classes/methods, I wonder: how will user that references my assemblies see that code example?

I tried to reference my own assembly, and the only way I found was: to look at assembly.xml file. Can I settle Visual Studio or anything else to see those code examples?

Here is what I put into comments:

/// <summary>
/// This is my method example
/// </summary>
/// <example>
/// <code>
/// // Here is my code example. Call my method like this:
/// const int a = 10;
/// MethodExample(a);
/// </code>
/// </example>
public static void MethodExample(int parameter)
{
}

Here is what I get in IntelliSense:

enter image description here

Here is what I get in Object Browser:

enter image description here

Here is what I get in assembly.xml file:

enter image description here

What I'd like to get: see code examples in Object Browser and IntelliSense.

Pang
  • 9,564
  • 146
  • 81
  • 122
Artem Kachanovskyi
  • 1,839
  • 2
  • 18
  • 27
  • 6
    Perhaps the `` tags are intended for use in generating documentation/specs. – Brian Warshaw Oct 29 '14 at 16:59
  • I don't even think you can get them showing in IntelliSense with ReSharper, perhaps another addin could do it, but that's not really what `` is for. – DavidG Oct 29 '14 at 17:04
  • 1
    I‘m going to suggest this as a feature so Quick Info/IntelliSense shows this. The support for XML comments when hovering over something or pressing Ctrl+K, Ctrl+I is not great. I would love to see all of the XML comments, otherwise it‘s almost pointless to write them. – bugybunny Nov 07 '18 at 08:48
  • 1
    If anyone wants to vote on it https://developercommunity.visualstudio.com/idea/377459/quick-infointellisense-should-show-more-of-xml-com.html – bugybunny Nov 07 '18 at 12:45
  • 1
    [This article in 2018](https://www.pluralsight.com/guides/using-code-example-tags-csharp-xml-documentation-comments) suggests that it might work as expected in VS Code. – CrazyTim May 13 '19 at 02:22

2 Answers2

11

A number of XML comment tags appear in IntelliSense only as child elements of other tags. These tags, known as ChildCompletionList tags, are: c, code, example, list, listheader, para, paramref, see and see also. 

/// <summary>
/// MethodExample the function that does it all...
/// <example>
/// <code>
/// <para/>// Here is my code example. Call my method like this:
/// <para/>const int a = 10;
/// <para/>MethodExample(a);
/// </code>
/// </example>
/// </summary>
Past Tense
  • 147
  • 5
  • 2
    What is the difference for end-user between this, and if I just put code inside summary without and tags? – Artem Kachanovskyi Oct 31 '14 at 08:25
  • 1
    The text for the tag is the only source of information about the type in IntelliSense. – jim31415 Oct 31 '14 at 11:56
  • 4
    In VS 2012, if I use the text in the code element displays unformatted in intellisense and in the object browser. Very ugly. – Jeremy Aug 26 '15 at 18:47
  • 1
    -1 This is not true with regards to the tag -- in the MSDN documentation, is listed as a separate top-level element, side-by-side with . See: https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/example – CJBS Sep 29 '17 at 22:19
  • 1
    @jim31415 RE "only source of information" -- do you have a link or reference where this is stated? – CJBS Sep 29 '17 at 22:22
  • 2
    @CJBS, "The tag is used by IntelliSense inside Visual Studio to display additional information about a type or member." So, if you want example usage information to display in intellisense, you would need to include that information in the block. https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/how-to-use-the-xml-documentation-features – jim31415 Oct 01 '17 at 11:56
3

If your not seeing XML commments in IntelliSense or they're not updating after you edit them try:

  1. Not seeing: be sure everything is enclosed in the <summary> element. ref: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags

  2. Not updating: close & reopen solution (this seems to work pretty consistently)

VS Ent 2019 (16.10.4)

Ken747
  • 107
  • 3
  • While this link may answer the question, it is better to include the essential parts of the answer here and provide the link for reference. Link-only answers can become invalid if the linked page changes. - [From Review](/review/late-answers/30131548) – Mark S. Oct 20 '21 at 19:51