Extract `TipFormatters` into its own package

[MangelMaxime]

Details

Hello,

I am working on improving F# formatting API documentation and one of the main element is to improve the Tooltip formatting.

This leads to having to duplicate TipFormatter code between FSAC and F# Formatting. Would you be ok if we make it a standalone package?

The portion of the TipFormatter that I would like to export is only the portion responsible for converting a XMLDoc into a formatted text.

It should correspond more or less to this portion of the file:

https://github.com/ionide/FsAutoComplete/blob/fc79e99f59c3da89cca0c1e4367307263228409d/src/FsAutoComplete.Core/TipFormatter.fs#L17-L858

Having a separate library means:

• Both project can benefit from improvements made to the XMLDoc formatter

• Add tests to capture future regressions.

  I think there are currently no tests regarding XMLDoc formatting in FSAC (at least I never wrote ones when I worked a lot with that portion of the code)

Extracting that portion of the code should not be too much of big deal because it doesn't depends on FSC or things complex like that. It just want an XMLElement and return a string / class instance.

It could be named something like Ionide.XMLDocFormatter? I worked on that code several times and volunteer to scaffold that project.

Checklist

• [X] I have looked through existing issues to make sure that this feature has not been requested before
• [X] I have provided a descriptive title for this issue
• [X] I am aware that even valid feature requests may be rejected if they do not align with the project's goals
• [X] I or my company would be willing to contribute this feature

[TheAngryByrd]

I think this is a good idea. Some other questions/thoughts.

• Should this be a separate repository?
  • If so, just another repository in the giant chain to update when FCS comes out with a new version.
• How much do we need to care about backwards compatibility/API stability?
• I know we have some issues with our tooltips being a bit too tied to VSCode display. Would this library need to know/allow for other formatting outputs? (Not extremely familiar with the TipFormatter code so maybe this is already addressable)

[MangelMaxime]

• Should this be a separate repository?

  • If so, just another repository in the giant chain to update when FCS comes out with a new version.

I would prefer it to be a separate repository because it is easier to maintain (at least for me). I already have all the infrastructure needed to handle automatic release based on Git history etc.

I only want to expose from Ionide.XMLDocFormatter something like XMLDoc -> string.

This way it is the job of FSAC and F# Formatting to resolve the XMLDoc location based on the project cracker / FCS API.

So I don't believe this library will be impacted by FCS release. It will just need Regex and XML API, so I don't think it will have anything dependencies beside NetStandard.

• How much do we need to care about backwards compatibility/API stability?

Only a portion of TipFormatter will be extracted and it should be backwards compatible. The main compatibility stuff to keep are the different styles of ToolTips we want to supports:

[<RequireQualifiedAccess>]
type FormatCommentStyle =
  | Legacy // Full text version of the tooltip
  | FullEnhanced // This is the default used by FSAC at the moment (markdown output with stripped exemples)
  | SummaryOnly // Markdown with summary content only
  | Documentation // Used by InfoPanel and probably F# Formatting (markdown with full content)

We could debate if Legacy is still needed, but every time I asked to remove it I was asked to not too 😅.

• I know we have some issues with our tooltips being a bit too tied to VSCode display. Would this library need to know/allow for other formatting outputs? (Not extremely familiar with the TipFormatter code so maybe this is already addressable)

This library will not need to know/allow for other formatting outputs. It will just need for FSAC/F# Formatting to tell which version of the Tooltip they want (see above).

Currently the tooltip is composed of:

1. Signature
2. XMLDoc comment
3. Open the documentation link
4. FullName info
5. Assembly info

The portion I want to extract is XMLDoc comment. While the part too tied to VSCode right now is Open the documentation link because it generates a VSCode command link which is not standard across LSP Servers.

This is part of FSAC LSPServer:

https://github.com/ionide/FsAutoComplete/blob/fc79e99f59c3da89cca0c1e4367307263228409d/src/FsAutoComplete/LspServers/AdaptiveFSharpLspServer.fs#L966-L987

[baronfel]

I'm generally in favor of this - my main comments are aligned with Jimmy. We need to keep an ability to define custom renderings for e.g. VSCode-specific clients vs NeoVim clients, for example.