dotnet / dotnet/dotnet-api-docs
Update documentation of `Type.IsAssignableFrom` and `Type.IsAssignableTo` when used with ref struct types
- Dominant language
- C#
- Stars
- 949
- Forks
- 1.7k
- Avg merge
- 3d 27m
- Merged PRs (30d)
- 49
Description
### Type of issue
Missing information
### Description
This issue is based on https://github.com/dotnet/runtime/issues/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](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.
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](https://discord.com/channels/143867839282020352/312132327348240384/1352981697930592266)).
So I think the documentation should be improved, but I'm not entirely sure how:
```diff
- 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
Contributor guide
Assessment
This issue has not been assessed yet.