Support compiled xml doc <code> tag

[gafter]

@AArnott commented on Mon Dec 21 2015

One reason examples don't get written in xml doc comments is they're hard to write and virtually impossible to maintain. Intellisense doesn't help write them, and refactoring and changing code later doesn't keep them current.

Suppose <code> snippets were recognized by the compiler and treated as regular code, including compile errors and refactoring, but just not emitted into the assembly at compile time?

There would of course be plenty of details to work out, such as what the context would be of the sample code (is it a statement block, or can it define types and members, etc.). But the result would be awesome pretty much wherever it lands.

In this snippet, for instance, the first example is correct but the second example would produce a compile error:

/// <summary>Adds two numbers</summary>
/// <param name="a">The first number</param>
/// <param name="b">The second number</param>
/// <example>
/// <code>
/// int five = Add(3, 2);
/// </code>
/// </example>
/// <example>
/// <code>
/// float five = Add(3, 2);
/// </code>
/// </example>
public static int Add(int a, int b) => a + b;

And syntax highlighting and autocomplete and the rest of the goodness would exist in those examples.

---

@m0sa commented on Mon Dec 21 2015

I like the idea. But according to this MSDN article, this should rather be done for <code> (and <c>) tags:

/// <summary>
/// The GetZero method.
/// </summary>
/// <example> 
/// This sample shows how to call the <see cref="GetZero"/> method.
/// <code>
/// class TestClass 
/// {
///     static int Main() 
///     {
///         return GetZero();
///     }
/// }
/// </code>
/// </example>
public static int GetZero()
{
    return 0;
}

---

@SergeyZhurikhin commented on Tue Dec 22 2015

@AArnott Correct title: <example> to <code>.

Furthermore, I agree with the @AArnott. I often write examples and at the moment, this work looks very strange. I'm writing a example of a free plot file using intellisense, and then insert in xml comment while doing shamanic dancing when copying - just when copying /// signs do not appear.

---

@alrz commented on Tue Dec 22 2015

👍

---

@daveaglick commented on Tue Dec 22 2015

👍

Also agree with others that this should apply to <code> and not <example>. I don't think there would be much value in supporting <c> since those are usually just short snippets devoid of context.

We'd also need a way to turn it off on a per-element basis. Perhaps a new compile attribute:

/// <summary>
/// The GetZero method.
/// </summary>
/// <example> 
/// This sample shows how to call the <see cref="GetZero"/> method.
/// <code compile="false">
/// class TestClass 
/// {
///     static int Main() 
///     {
///         return GetZero();
///     }
/// }
/// </code>
/// </example>
public static int GetZero()
{
    return 0;
}

---

@AArnott commented on Tue Dec 22 2015

Thanks for the correction on using <code> instead of <example>. I've made the proposed change.

---

@davkean commented on Tue Dec 22 2015

@gafter What do you want this under? Language Design?

---

@sharwell commented on Tue Dec 22 2015

SHFB expands on support for <code> elements, allowing placement of content in other files.

• Example usage
• Example output

Even if C# support worked per this feature request, it would be difficult to make it support other languages without going to route described above.