Proposal: Add support for code examples in metadata documentations

[AraHaan]

Like for example one wants to include a example to call their api in their assembly's metadata so the end user does not have to go and view their documentation many times just to get an idea how to call it. A valid example is System.Drawing.Bitmap.GetFrameCount() where the documentation did not provide a example of how to get a FrameDimention until I looked all over google to find a example because msdn lacks that example for it.

I was thinking maybe something like this would suffice:

/// <summary>
/// A example method.
/// </summary>
/// <example>
/// example_m("example string.");
/// </example>
public static void example_m(string example)
{
    Console.WriteLine(example);
}

However things like Visual Studio's Intelisence (that seems to use Roslyn for the context menus for methods) would probably then have to show the example calls too like so:

Examples:
    example_m("example string.");
    <and possible others for optional parameters for this specific method or overload.

In fact it might also help improve the documentations on .NET Core/Standard/Framework/Mono to use this feature and possibly fix the issue of System.Drawing.Bitmap.GetFrameCount() not having a example call in MSDN (and where and how to get the parameter it takes in).

[AraHaan]

cc: @tannergooding

[svick]

The spec already includes the <example> tag. And for example Rider can also show its content in a popup (I have modified the doc comment to add <code> inside the example, as the spec suggests):

If VS does not show it or recommend using it, and you want to change that, then I think this request would belong to the dotnet/roslyn repo.

[AraHaan]

ah ok.

[svick]

In fact it might also help improve the documentations on .NET Core/Standard/Framework/Mono to use this feature and possibly fix the issue of System.Drawing.Bitmap.GetFrameCount() not having a example call in MSDN (and where and how to get the parameter it takes in).

I believe most of .Net API reference documentation does not use documentation comments as their source. If you have a suggestion on how to improve an article in the documentation, you should use the Feedback section at the bottom of the article (it helps you create an issue in the appropriate documentation repo on GitHub).

[AraHaan]

I also wanted the spec example one to also support multiple ones as well (in which case the title of the example section in rider would be renamed to Examples and list the examples provided in order).

[BhaaLseN]

Sounds familiar. dotnet/roslyn#26504