API docs should handle Markdown content

[rmunn]

Is your feature request related to a problem? Please describe. One of the nice features about FSharp.Formatting is how it can process Markdown in doc comments. I'd like to be able to do the same with the docsTool included in the scaffold, preferably by leveraging FSharp.Formatting so we don't have to reinvent the wheel.

Describe the solution you'd like I'd like to be able to write something like:

    /// Number of items in list. **O(1)**
    abstract member Length : int

And have the compiled documentation render as:

x.Length        int        Number of items in list. O(1)

Currently to get that formatting in the documentation, I have to write HTML tags in my comments:

    /// Number of items in list. <b>O(1)</b>
    abstract member Length : int

Describe alternatives you've considered Just writing HTML tags into the documentation works, and it's not too burdensome when I'm just wanting to highlight a few items in bold.

Additional context There are many more things that might be desirable, like parsing `name` in a doc comment, noticing that name is the name of a parameter in the decorated function, and turning that into a <param> element. What, exactly, should be in scope or out of scope for this idea is a very open question.

[TheAngryByrd]

The main reason I went with XML is the the discussion in this issue. Markdown docs also don't look good in other IDEs like Visual Studio or Rider.

Essentially it boiled down to the markdown doc comments isn't supported well in many contexts. I personally love using markdown and would favor it if we could get better support for it in other places.

[rmunn]

Fair point, I guess we need to make a push to get Markdown-in-docs better supported in other IDEs and then we'll be able to revisit this idea. I think Rider, being a newer project, might be more likely to pick up the idea first. Then the Ionide guys would be happy to add the Markdown back in, and then with VS Code (at least in the Ionide plugin) and Rider both handling Markdown in docs, we might be able to put more pressure on the Visual Studio team to join the modern world. ;-)

But I guess I'll close this issue until some future date when that might happen. It doesn't really make sense for the MiniScaffold-generated API docs to turn Markdown into XML/HTML tags right now, since that wouldn't be saved in the .DLL and so no IDE would see those tags. If that feature is going to happen, it would make more sense for it to happen in FSAC first. Then if MiniScaffold's docsTool needs to change in any way, we can revisit this idea.