F# 9 doc updates

[psfinaki]

Related: dotnet/fsharp#17829.

Docs for F# 9, aligning with what's new.

This does not include Nullable Reference Types stuff, yet - will do as a follow up.

---

Internal previews

📄 File	🔗 Preview link
docs/fsharp/language-reference/active-patterns.md	Active Patterns
docs/fsharp/language-reference/attributes.md	Attributes
docs/fsharp/language-reference/byrefs.md	Byrefs
docs/fsharp/language-reference/compiler-directives.md	Compiler Directives
docs/fsharp/language-reference/computation-expressions.md	Computation Expressions
docs/fsharp/language-reference/discriminated-unions.md	docs/fsharp/language-reference/discriminated-unions
docs/fsharp/language-reference/fsharp-collection-types.md	F# collection types
docs/fsharp/tools/fsharp-interactive/index.md	Interactive programming with F#

[T-Gro]

Do https://learn.microsoft.com/en-us/dotnet/fsharp/language-reference/attributes need a change w.r.t to attribute targets and special cases caused by F# representation of types and let bindings?

[T-Gro]

Was expecting to see "allow ref struct" interop support.
Affects structs, byref types, type constraints.

Also affect type augmentations which now are not possible (e.g. for seq<>) and people have to use C# style extension method.

[T-Gro]

https://learn.microsoft.com/en-us/dotnet/fsharp/language-reference/discriminated-unions#struct-discriminated-unions

Has a section about needing "unique names", i.e. not describing the state after F# 9.

[T-Gro]

As part as equality for structs in generic context is concerned, shouldn't the IEquatable interface now also be relevant for F#-authored types?

https://learn.microsoft.com/en-us/dotnet/fsharp/language-reference/symbol-and-operator-reference/arithmetic-operators#overloaded-and-generic-operators

[psfinaki]

Do https://learn.microsoft.com/en-us/dotnet/fsharp/language-reference/attributes need a change w.r.t to attribute targets and special cases caused by F# representation of types and let bindings?

I don't think so. I was looking at that but didn't find anything that has become wrong now. It talks of targets and so on, but generally nothing new there - even the raised diag has been there forever, just better reported now.

Was expecting to see "allow ref struct" interop support.
Affects structs, byref types, type constraints.

Hmmm, what in particular? We don't have anything about that in "what's new", nor can I find any mention of ref structs in the docs currently. And that's not something I was following really, so I have little understanding of the topic - so I need either something to copypaste, or some time to understand what's it all about.

https://learn.microsoft.com/en-us/dotnet/fsharp/language-reference/discriminated-unions#struct-discriminated-unions
Has a section about needing "unique names", i.e. not describing the state after F# 9.

Correct, missed that - fixed, thanks.

As part as equality for structs in generic context is concerned, shouldn't the IEquatable interface now also be relevant for F#-authored types?

Well, relevant in which sense? The added generated method doesn't implement any interface.

[T-Gro]

Ok, I have read all of those.

Re: Attributes
The table of attribute targets does not include f#-native types, like functions or DUs where the most impactful changes were.
Also, the table of attribute targets does not include other very common targets (does not have to include all though) which were part of the affected changes. e.g. struct, enum or method.

Especially in the case of not having an exact 1:1 lowering, this page should list the samples well. (e.g. how a let x = 5 differs from let x = 15, how DUs differ from enums etc.). Should be all in PRs on the topic.

Re: Allows Ref Struct:
Best would be check that PR on the topic, this changes what is allowed for generic parameters and consume it from F#.
This affects type augmentations, since in F#-authored code they cannot now be used for C#-defined type using "T:allows ref struct". Users have to switch to C#-style extensions. Best example is: Try a type augmentation for seq, it will fail due to not meeting generic constraints.

Re: Equality:
Ok I studied it. I do think it affects people writing their own equality via [<CustomEquality>] and not using the generated one.
For optimal performance, especially within structs in generic context, they should add overload similar to public bool Equals(SomeStruct obj, IEqualityComparer comp), or?

[psfinaki]

Re: Attributes

Okay, added examples for methods, classes, interfaces and what not.

Re: ref structs and custom equality

We currently don't have anything on those topics in the docs. Both things deserve their own pages really, as I don't think there is a good way to "plug" them to existing topics.

The point of this PR is to "fix" the docs which are becoming misleading or wrong with the F# 9 update. For the missing topics, we can create followups or just tasks here in the repo.

[T-Gro]

Ok I searched the docs for it:

There is a full page dedicated to byrefs here https://learn.microsoft.com/en-us/dotnet/fsharp/language-reference/byrefs , and it does have a section for byreflikes which this affects.

(because byreflikes are now allowed to be passed as type instantions to selected BCL generic types|)

Right now the docs page says:
https://learn.microsoft.com/en-us/dotnet/fsharp/language-reference/byrefs#byref-like-structs
"They cannot be used as a generic parameter"

[psfinaki]

Right, I didn't connect ref struct and byrefs - I really don't follow low-level stuff in F#🤷

I copypasted the info from the updated RFC, hope it's clearer now.

[T-Gro]

@BillWagner , @KathleenDollard :

Excluding all changes touching null, this F# 9 docs update is ready. Can we merge?

[BillWagner]

This LGTM as well. I'll now.