Fsharp: Documentation Overhaul

[cloudRoutine]

As I've been working on updating and improving FSharp.Formatting I've had some thoughts about how we can improve the experience of writing F# documentation, consuming documentation, and building tools to provide documentation.

---

Parity with C# Features

Improving editor tooling support to the level currently enjoyed by C# in Visual Studio should be the bare minimum that we shoot for.

• Syntax/Tag Highlighting within the documentation comment

• Completions for xml tags and paramaters, args, etc.

• Auto-close xml tags

Fix Rendering Inconsitencies

• F# does not follow the conventions used by C# for how it presents text in the documentation comments

Granted what C# does regarding the tooltip size is pretty terrible (and we should at least address the size by allowing the user to set a max height and width for the intellisense tooltips), within XML style documentation comments we should at least follow the rules regarding line breaks

Properly Support Listed XML Tags

Currently of the tags listed in the F# documentation the
only ones that currently work properly are <summary>, <exception>, and <para>. We should extend support to the set of tags that C# Supports -

<c>     <para>  <see>*
<code>  <param>*    <seealso>*
<example>   <paramref>  <summary>
<exception>*    <typeparam>*
<include>*  <remarks>   <typeparamref>
<list>  <returns>   <value>

( * denotes that the compiler verifies syntax.)

<b> & <i> should also be supported in summary, remarks, example, etc.

---

Improve FCS API for Consuming Tooltips

I think the model that is used for the documentation data could be improved using something like -

  type ConstructCategory = 
      | Keyword | Identifier | Operator | Preprocessor | Class 
      | ValueType | Union | Record | Property| Enumeration 
      | UnionCase | TypeArgument | Interface | Function  | Pattern

  type DocsFormat = Xml | Markdown

  type DocData = {
      Category : ConstructCategory
      Paramaters : string list
      TypeParamaters : string list
      Exceptions : string list
      Returns : string
      Format : DocsFormat
      Summary : string
      Example : string
      See : string
      Value : string
      SeeAlso : string
  }

Creating an individual data record type for each construct category is another option
so they only contain the relevant data.

I realize this is simalr to FSharpMethodGroupItemParameters, FSharpMethodGroupItem, etc. but I
think that we could have a better set of types to model this data oriented toward external
consumption.

---

Markdown Styled Documentation Comments

We're already working in an environment where F# Documentation comments are being parsed
for markdown so we should take better advatage of it

VsCode already supports markdown to great effect

But in Visual Studio it looks terrible

DocFx ( which is used to generate the official F# help documentation ) also already supports markdown

FSharp.Formatting parses comments for markdown to build webpages.

There are several disadvatanges to the ///

• it makes reformatting comment contents difficult (e.g. indents)
• not great for cut & paste
• makes markdown usage ambiguous

I don't think that markdown style and xml style should be mixed which is why
markdown styled documentation comments could follow conventions similar to [the
ones that OcamlDoc uses] (https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sec349) (** **)

XCode's scope goes further than what i think is necessary, especially the callouts if markdown is going to be supported

This new style of documentation comments wouldn't be supported by DocFx straight out of the gate, but we can easily extend it to support whatever conventions we decide upon

---

Detailed Info Tool Window

I totally understand that building this tool window is out of scope for the F# VS tooling, but the point I'm trying to make is that we should make it easy to build this kind of tool even if it's included with VisualFSharp.

this is the tooltip for Async.OnCancel

This is the documentation comment in the signature file containing Async.OnCancel

That's some really useful information, it'd be great if we were able to see it in VS somehow, especially since we already have it in FSharp.Core.xml

Async sure does have a lot of methods, it'd be nice if we could see all of them and their respective documentation comments

Between the content of the xml files for the libraries and the metadata in the .dlls we could do a lot more to surface useful information to F# devs that's right
under their fingertips if only they knew how to look.

It would be like a much improved version of the Quick Help Inspector in XCode

---

References

• C# Xml Documentation
• F# Xml Documentation
• XCode Markup Functionality
• DocFx /// Code Comment Support
• OCamlDoc Syntax

(BTW these aren't "I hope someone else will do this" suggestions, I'm more than willing to implement all of this myself)

[matthid]

Agreed, one fundamental problem is that we have not decided on a syntax yet. Is it markdown or xml? If both then how/where do we tell/detect the difference?

[cloudRoutine]

@matthid i was thinking it'd be like

///  <summary>
///  xml doccoms
/// </summary>

(**
   markdown doccom
**)

Both would be parsed and stored as xml like normal though. The conversion is pretty simple, ionide already converts from xml to markdown to create the tooltips
would be for xml and (** **)

[realvictorprm]

I really like how Javadocs work and appear in the most used editors. So I would vote for Javadoc like styling.

This is something I miss very much from VS tooling.

[enricosada]

The Quick Help Inspector in XCode is really nice.
lot of additional MSDN docs is never shown, and will be good to have with a shortcut (not F1 😄 )

[majocha]

Tool window for docs would be awesome!

About markdown: Since there already exists codebase which uses markdown with /// comments, can't we just support it by default wherever it makes sense. I'm thinking exclude <code>, <pre> and parse all the rest for markdown, with an option to turn this off?

Another feature I'd love to see is some linebreaks and formatting of overly long type and member signatures.

[cloudRoutine]

@majocha the existing markdown codebases will markdown doccoms will just have to update. Once there's a standard they can adjust to it. I'm a maintainer of most of the projects that make the most extensive use of it, so I can just fix those myself 😉

[dsyme]

@cloudRoutine

I really like the thinking here

... I was thinking it would be like...

I'm not at all keen on requiring (** ... **).

Would it be plausible to make /// without an explicit <summary> tag or any other explicit XML tags or &... escapes mean markdown? The compiler would still generate an XML file if requested, but the default presentation would be based on markdown rules.

///  markdown doccom