search

dotnet / dotnet-api-docs

.NET API reference documentation (.NET 5+, .NET Core, .NET Framework)
https://docs.microsoft.com/dotnet/api/
Other
688 stars 1.52k forks source link

Wrong Summary & Return Value Descriptions for BigInteger.MinMagnitude & BigInteger.MaxMagnitude #9525

Open zacharylayne opened 7 months ago

zacharylayne commented 7 months ago

BigInteger.MinMagnitude reads: Summary: Compares two values to compute which is lesser.

x The value to compare with y. y The value to compare with x.

Returns: x if it is less than y; otherwise, y.


This would indicate the method is no different than Min.


Instead, MinMagnitude should be:

Summary: Returns the BigInteger with the smallest absolute value.

Returns: The BigInteger with the smallest absolute value. If the absolute values are equal, returns x if x < 0 and y if x >= 0.


BigInteger.MaxMagnitude documentation has the same issue.

ghost commented 7 months ago

Tagging subscribers to this area: @dotnet/area-system-numerics See info in area-owners.md if you want to be subscribed.

Issue Details
[BigInteger.MinMagnitude](https://learn.microsoft.com/en-us/dotnet/api/system.numerics.biginteger.minmagnitude?view=net-8.0) reads: **Summary:** *Compares two values to compute which is lesser.* **x** *The value to compare with y.* **y** *The value to compare with x.* **Returns:** *x if it is less than y; otherwise, y.*
This would indicate the method is no different than [Min](BigInteger.Min).
Instead, **MinMagnitude** should be: **Summary:** *Returns the [BigInteger](https://learn.microsoft.com/en-us/dotnet/api/system.numerics.biginteger?view=net-8.0) with the smallest absolute value.* **Returns:** *The [BigInteger](https://learn.microsoft.com/en-us/dotnet/api/system.numerics.biginteger?view=net-8.0) with the smallest absolute value. If the absolute values are equal, returns `x` if `x` < `0` and `y` if `x` >= 0.*
[BigInteger.MaxMagnitude](https://learn.microsoft.com/en-us/dotnet/api/system.numerics.biginteger.maxmagnitude?view=net-8.0) documentation has the same issue.
Author: zacharylayne
Assignees: -
Labels: `untriaged`, `Pri3`, `area-System.Numerics`, `:watch: Not Triaged`
Milestone: -
gewarren commented 7 months ago

Related to #9468.

zacharylayne commented 4 months ago

@gewarren Can I make the change myself? I think if I do, they will be overwritten by some API change, however the updates to INumberBase are not reflected in the API reference. Is this related to the type being forwarded or anything?

gewarren commented 4 months ago

@gewarren Can I make the change myself? I think if I do, they will be overwritten by some API change, however the updates to INumberBase are not reflected in the API reference. Is this related to the type being forwarded or anything?

@zacharylayne Yes, you can make the change yourself. Since it's under the \ element, it won't be overwritten. Also, can you clarify what you mean by "the updates to INumberBase aren't reflected in the API reference"? I see the changes from #9468 here: https://learn.microsoft.com/en-us/dotnet/api/system.numerics.inumberbase-1.minmagnitude?view=net-8.0.