Update documentation of Type.IsAssignableFrom and Type.IsAssignableTo when used with ref struct types

[Enderlook]

Type of issue

Missing information

Description

This issue is based on dotnet/runtime#113787
The summary and remarks documentation of this method (and IsAssignableTo) are somewhat ambiguous when testing types that are ref struct.

The summary stands for:

Determines whether an instance of a specified type c can be assigned to a variable of the current type.

And the remarks:

The IsAssignableFrom method can be used to determine whether an instance of c can be assigned to an instance of the current type, The method is most useful when you are handling objects whose types are not known at design time and allows for conditional assignment, as the following example shows.

However, that is technically not true for ref struct types, as typeof(object).IsAssignableFrom(typeof(MyRefStruct)) returns true, but isn't possible to assign such value to a variable of type object because ref struct types can't be boxed.

Instead, in the issue linked, it's stated that IsAssignableFrom (and [...]To):

Reflection IsAssignableFrom API operates on (conceptually) boxed values. It is answering a question: If you were able to obtain a boxed value of the given type, would that value be assignable to the target type? It is not trying to answer whether it is possible to obtain such boxed value.

I find such distinction quite important to include in the documentation, as I got taken by surprise when the method returned true, yet I was not able to assign such value, despite the summary documentation stating that if the method returned true I could assign the value. Such surprise was, that when asked in a C# discord channel, a few users started arguing if this was a bug or not in the implementation, as it was left to some interpretation (starting at message).

So I think the documentation should be improved, but I'm not entirely sure how:

- Determines whether an instance of a specified type `c` can be assigned to a variable of the current type.
+ Determines whether a (conceptually) boxed instance of a specified type `c` can be assigned to a variable of the current type. That is, if you acquired a boxed value of the type `c`, this determines if it could be assigned to a variable of the current type.

- The [IsAssignableFrom](https://learn.microsoft.com/en-us/dotnet/api/system.type.isassignablefrom?view=net-9.0) method can be used to determine whether an instance of `c` can be assigned to an instance of the current type, The method is most useful when you are handling objects whose types are not known at design time and allows for conditional assignment, as the following example shows.
+ The [IsAssignableFrom](https://learn.microsoft.com/en-us/dotnet/api/system.type.isassignablefrom?view=net-9.0) method can be used to determine whether an instance of `c` can be assigned to an instance of the current type (as long as neither type is a by ref like type, such as `ref struct`), The method is most useful when you are handling objects whose types are not known at design time and allows for conditional assignment, as the following example shows.

Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.type.isassignablefrom?view=net-9.0#returns

Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System/Type.xml

Document Version Independent Id

6821d06b-b052-e2cc-441e-755615bfb8bb

Platform Id

959fc1c0-d8d1-3c0f-3707-bec285810120

Article author

@dotnet-bot

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-runtime