Support markdown in documentation comments

[baronfel]

Submitted by Anonymous on 4/2/2014 12:00:00 AM
19 votes on UserVoice prior to migration

F# currently supports documentation comments with either XML tags or no tags. The no tags format is convenient to write, but does not allow formatting the comments for the VS IDE. Use of XML tags allows formatting the documentation comment, but the act of writing the documentation comment becomes a heavy burden as XML is not a very convenient format for manual editing. I would like to suggest supporting some lighter-weight formatting syntax such as markdown.

Original UserVoice Submission
Archived Uservoice Comments

[dsyme]

Just to note the markdown comments accepted by FSharp.Formatting are documented here: https://fsprojects.github.io/FSharp.Formatting/apidocs.html#Markdown-Comments

[dsyme]

Also, this RFC is orthogonal but relevant https://github.com/fsharp/fslang-design/blob/master/tooling/FST-1031-xmldoc-extensions.md

[pblasucci]

I'm not opposed to supporting Markdown as a purely stylistic mechanism. However, I'd be really disappointed if folks (i.e. tooling authors) started attaching semantic meaning to various Markdown (really HTML) constructs. Though, I'll admit, I'm not sure if there's a good way to enforce "use XML for semantics; use Markdown for styling" (especially since the tooling suggesting linked above advocates for honouring a few basic HTML constructs).

[Tarmil]

Two points I think need to be kept in mind:

• As noted in FST-1031, XML docs are actually used for two very different purposes: IDE tooltips and reference documentation. In a way, XMLdoc top-level tags are separated in two categories: those that show up in tooltips (<summary>, <param>, <returns>, etc) one one hand, and those that don't (<remarks>, <example>, etc and custom tags) and are therefore only destined for reference documentation on the other hand. Let's call these tooltip tags and refdoc tags.

• Editor support is unequal regarding tooltips. Ionide formats them as markdown. VS doesn't, but it does have some support for HTML. In VS, a tooltip like this:

  /// <summary>
  /// This is a <b><a href="http://google.com">test</a></b>.
  /// A **[big test](http://google.com)**.
  /// </summary>

  shows up like this:
  

  An unfortunate consequence is that there are currently packages out there, created by people who only use Ionide, that already contain markdown in their summaries and look odd or are even hard to read in VS.

  This is also not just a matter of adding markdown support to VS's F# mode when displaying tooltips: F# libraries are also consumed by C# users!

So if we want to be able to use markdown in summaries and have them show up nicely in all editors, the transformation from markdown to HTML must be done by the compiler when generating the XML file.

We would probably want to keep this markdown transformation pretty simple, supporting basic markdown syntax only, for the sake of not bringing too much complexity into the compiler. But we also don't want to prevent people from using advanced markdown extensions in their own reference documentation (using FSharp.Formatting or any other custom tool) if they want to! So maybe we should transform tooltip tags to HTML but leave refdoc tags alone?

[baronfel]

An unfortunate consequence is that there are currently packages out there, created by people who only use Ionide, that already contain markdown in their summaries and look odd or are even hard to read in VS.

Brief side note here that we've reverted this default functionality in FSAC/Ionide and now only generate XML documentation. We do transform the generated docs into markdown for VSCode, but that's only because the LSP spec for tooltips requires that, we're working from full-fidelity XML as the root data source.

[Tarmil]

Ah, thanks for the info, I didn't know that!

[cartermp]

These would have to be in some specialized node that C# and VB can ignore. Of course that would also mean that any future work to additionally support markdown in C#-emitted XML docs would complicate matters :)

[lukesdm]

An unfortunate consequence is that there are currently packages out there, created by people who only use Ionide, that already contain markdown in their summaries and look odd or are even hard to read in VS.

And vice versa - people that primarily use VS (but not FSDoc) unknowingly adding markdown to comments, which look wacky in Ionide. It seems the 'right' answer is that Markdown in comments is a de facto part of the language, and Visual Studio has a deficiency here which should be addressed - at the very least, mentioned in the docs.
Edit: Rider also has different behaviour.
Comparison of the 3 main IDEs...
Rider:

Ionide:

Visual Studio: