fsprojects / FSharp.Formatting

F# tools for generating documentation (Markdown processor and F# code formatter)
https://fsprojects.github.io/FSharp.Formatting/
Other
462 stars 155 forks source link

Make a better attempt at finding intended member for <seealso> #789

Closed davedawkins closed 1 year ago

davedawkins commented 1 year ago

In this example

/// <summary>
/// Dispose all given items when the parent <c>SutilElement</c> is unmounted. Each item should implement <c>System.IDisposable</c>.
///
/// See also: <seealso cref="M:Sutil.DOM.unsubscribeOnUnmount"/>
/// </summary>

I'm not providing the full signature for unsubscribeOnUmount, because:

Actual signature

M:Sutil.DOM.unsubscribeOnUnmount(Microsoft.FSharp.Collections.FSharpList{Microsoft.FSharp.Core.FSharpFunc{Microsoft.FSharp.Core.Unit,Microsoft.FSharp.Core.Unit}})

It's all noise and friction.

Currently fsdocs makes an effort to find something to link to, but stops at the containing enitty (in this case Sutil.DOM).

I've written a small amount of code that tries a little bit harder and goes on to find the actual member being specified. It stops at the first match, so overloads are an issue. Still, I think this adds value to the experience of writing docs.

I will send a PR.

baronfel commented 1 year ago

Another approach here would be to make the F# compiler always embed the fully qualified form, but let users write the simpler forms in the XMLDoc. This is what C# does and it feels very nice. Devs only have to worry about using the 'normal' names of things, and the compiler generates and uses the doc signature strings behind the scenes.

davedawkins commented 1 year ago

That would also be welcome. I've made the PR now.

davedawkins commented 1 year ago

This PR now included in 17.2.2