Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
davedawkins opened this issue Jan 15, 2023 · 3 comments
Closed

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

davedawkins opened this issue Jan 15, 2023 · 3 comments

Comments

@davedawkins
Copy link
Contributor

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:

  • it's extremely noisy (and ugly) - see below
  • I'd have to look in a generated XML file

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
Copy link
Collaborator

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
Copy link
Contributor Author

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

@davedawkins
Copy link
Contributor Author

This PR now included in 17.2.2

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants