I propose to revisit the documentation to use "signature-like" to describe the API documentation. This is also to makes the most out of the XML doc comment.

Here is a comparaison between what I propose and the currently generated documentation by F# formatting using Fable.Promise package as a reference. Fable.Promise has been crafted to take the most out of the XML doc comment.

• Instead of using a table like layout with the function or member name on the left with the documentation on the right, the new proposition use a vertical layout.
• The tooltip formatting can be improved by re-using the formatting used in FsAutoComplete.

Here is another exemple for a record type:

To have a look at my proposition, you can go to Fable.Promise. It mainly use functions.

If you want to see more complex API documentation with a mix of functions and records, you can clone https://github.com/MangelMaxime/Nacara/tree/fsharp-docs-example and then use npx http-server to host it locally. It is not available online anymore, because of a broken thing since the project moved to NET6.0

I will have a look in the coming days, to send a pull request to see what it means in term of changes of F# Formatting.