Add support for the `example` documentation comment tag

[baronfel]

Add support for the example documentation comment tag

I propose we add support for the example documentation comment tag as in C#: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/example. This would allow library authors the provide inline samples for functions that could be surfaced in tooling such as extended tooltips or more detailed views like the Object Explorer in Visual Studio or the Info Panel in Ionide.

As a stretch, the code in such tags could even be typechecked in a way similar to Rust's example blocks:

• Rust Documentation Examples
• Rust documentation guidelines

Pros and Cons

The advantages of making this adjustment to F# are better 'defaults' available with less user effort. With examples attached to the functions themselves (and even moreso if those are typechecked) it's much more likely that a) documentation will exist at all for the function and b) that it remains in line with changes to the function over the course of editing.

The disadvantages of making this adjustment to F# are the amount of work it involves. Allowing for examples themselves (as just code samples that are in no way checked) I would estimate at an S or M, because it involves updating the documentation structures and passing that representation through to PDBs and FCS, but adding typechecking of them I would estimate at an M to L, primarily because of the work involved with assembling an accurate typecheck environment for each sample. Determining what symbols would be in scope for each typechecked example would be nontrivial.

Extra information

Estimated cost (XS, S, M, L, XL, XXL):

• Just adding code examples: S/M
• Typechecking those examples: M/L

Related suggestions: (put links to related suggestions here): None that I found

Affidavit (please submit!)

Please tick this by placing a cross in the box:

• [x] This is not a question (e.g. like one you might ask on stackoverflow) and I have searched stackoverflow for discussions of this issue
• [x] I have searched both open and closed suggestions on this site and believe this is not a duplicate
• [x] This is not something which has obviously "already been decided" in previous versions of F#. If you're questioning a fundamental design decision that has obviously already been taken (e.g. "Make F# untyped") then please don't submit it.

Please tick all that apply:

• [ ] This is not a breaking change to the F# language design
• [x] I or my company would be willing to help implement and/or test this

[dsyme]

@cartermp What do you think?

[smoothdeveloper]

My 2 cents, we may have two separate suggestions:

• one to match the example xml doc tag in C#
• one for the type checked blocks that could be surfaced / appended to the (existing or not) example tag

Work on the implementation in the compiler should be approached while keeping in mind retargetting the internal documentation representation to different supports / ecosystems is going to be important in the long term, ideally of course.

Supporting the first part in a near release seems kind of urgent to me, usage of that tag in C# for public APIs is pervasive enough to bring F# on par.

[cartermp]

I'd love it.

[baronfel]

@smoothdeveloper I agree that I've conflated the two use cases, and I agree that at minimum is like to see examples be authorable and visible in documentation tools like the Object Explorer or Ionide Info Pane. I mostly mentioned them in the same suggestion because I want to help guide the expectation that typechecked examples are a thing we should do.

[dsyme]

The example tag exists and is populated for FSharp.Core now - @baronfel is this suggestion about authoring tooling (e.g. code highlighting), or consuming tooling (object browser etc)?

Either way I don't think there's anything language-specific here, it's all about tooling from here on.

[baronfel]

It's covered by the xml tooling RFC, as well as broader support in FSharp.Formatting.

I think the only remaining gap is visibility in the VS IDE - Ionide users have access to these via tooltip and Info Panel, but I'm not sure how VS users would.