Use signature-like for documenting the API

[MangelMaxime]

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.

Note

The goal of this issue is to focus on improving the information presented to the user. Don't focus too much on the global layout / navigation differences.

• 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.

[nojaf]

Hello,

I think this is a reasonable request. I'm not aware of any strong attachments to our current setup. As long as the out-of-the-box experience works, we can revisit this.

This will require a major version, multiple alphas, and strong community collaboration. We're ready for this!

Some technical pointers:

• Focus on the content generation. We already have a solution for generating HTML in GenerateHtml.fs, so there's no need to revisit this part.
• Ensure the look and feel are consistent with our default template. All styling is handled in fsdocs-default.css, where we have many established CSS variables that should be reused. Add new variables if necessary.
• Support both light and dark modes.
• Ensure it works for our current users; examples can be provided if needed.
• Avoid breaking existing URLs with these changes.
• Verify that the search functionality remains intact, as it might be affected.

Tagging some contributors to keep them in the loop:
@nhirschey @kMutagene @brianrourkeboll @dsyme @teo-tsirpanis

[brianrourkeboll]

I'd definitely be interested in seeing a prototype of this.

• 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 current layout does technically switch to vertical when the viewport is below a certain width 😉

For what it's worth, both approaches — a compact side-by-side table of signatures and descriptions as well as a vertical list of signature headings with following descriptions — are used in various places in the docs on learn.microsoft.com.

• The tooltip formatting can be improved by re-using the formatting used in FsAutoComplete.

I assume you mean the formatting of signatures in general, whether in the tooltips shown on hover or elsewhere? Either way, I agree.

[MangelMaxime]

The current layout does technically switch to vertical when the viewport is below a certain width 😉

I didn't know that we will be able to iterate over it once the basics of generating the new signature is in place.

For what it's worth, both approaches — a compact side-by-side table of signatures and descriptions as well as a vertical list of signature headings with following descriptions — are used in various places in the docs on learn.microsoft.com.

I believe that doing so means a new page is needed to "enter" inside the member or function declaration. I personally, like the approach that Elm takes with having everything on a single page because it allows to easily search using Ctrl+F on the page versus having to jump between different links/pages.

This change was not in my mind with this issue, but depending on the UX we get once we have a first prototype perhaps it will make sense to add.

I assume you mean the formatting of signatures in general

Here, I was talking about the formatting of the XML Doc.

[brianrourkeboll]

@MangelMaxime Sorry, yeah, I didn't mean to imply that the existing "vertical" layout was good enough or should be kept — you can ignore that comment.

I also didn't mean to imply that we necessarily need or want something exactly like the MS docs — I just brought them up as a point of comparison.

Basically, ignore everything I said :)

[MangelMaxime]

No worries, the goal is for everyone to voice in :)

Your suggestions are good, and I believe they can be considered depending how the user experience we want to offer. I believe most of the layout changes / improvements will be made later in the process once we have the basics for structuring the new content.

I am planning on working on it tomorrow and hope I will soon be able to send a PR. I first need to learn a bit about F# Formatting internals etc. :)

[MangelMaxime]

For anyone interested, an experimentation with explanation of the problems encountered is available in the PR above.

[nojaf]

This experiment is currently making us consider breaking ApiDocs.GenerateHtml. It would still return the same object but the HTML would be different.

Could this be problematic for someone? Shot in the dark, people who might use this are @Thorium or @kMutagene. Any thoughts on this? If you are using this, what is your use-case?