Explain what "normal" is in Single.IsNormal#12280
Explain what "normal" is in Single.IsNormal#12280sfiruch wants to merge 1 commit intodotnet:mainfrom
Conversation
|
Tagging subscribers to this area: @dotnet/area-system-runtime |
There was a problem hiding this comment.
Pull request overview
This PR improves the documentation for Single.IsNormal by expanding the summary to explain what "normal" means in the context of floating-point numbers, rather than using the technical term without explanation.
Changes:
- Updated the
<summary>element forSingle.IsNormalto explicitly state what constitutes a "normal" floating-point value (not NaN, not infinite, not subnormal, and not zero)
| <Docs> | ||
| <param name="f">A single-precision floating-point number.</param> | ||
| <summary>Determines whether the specified value is normal.</summary> | ||
| <summary>Determines whether the specified value is not NaN, not infinite, not subnormal, and not zero.</summary> |
There was a problem hiding this comment.
The summary now duplicates the remarks section verbatim. This creates unnecessary redundancy. The consistent pattern in Double.IsNormal (xml/System/Double.xml:2950) and Half.IsNormal (xml/System/Half.xml:2219) is to have a brief summary like "Determines whether the specified value is normal" and then provide the detailed explanation in the remarks section. Consider keeping the summary concise and letting the remarks section provide the detailed explanation of what "normal" means.
| <summary>Determines whether the specified value is not NaN, not infinite, not subnormal, and not zero.</summary> | |
| <summary>Determines whether the specified value is normal.</summary> |
|
This should probably be combined into the same PR with #12281 and with the same feedback given there addressed. |
Summary
The documentation for Single.IsNormal is wholly unhelpful. It says it checks if a number is "Normal". Only in the remarks, "normal" is explained. This changes it to make it clear what it actually checks.