Convert.ToString(object, IFormatProvider) overload docs are misleading

[inosik]

Type of issue

Other

Description

The docs of Convert.ToString(object, IFormatProvider) state this:

Returns
The string representation of value, or Empty if value is an object whose value is null. If value is null, the method returns null.

These parts are contradictory:

[...] Empty if value is an object whose value is null.

If value is null, the method returns null.

The last one is especially misleading, because it isn't true. This method returns an empty string if value is null. Just as the ToString(object) overload does, and correctly documents:

Returns
The string representation of value, or Empty if value is null.

This applies to all frameworks.

Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.convert.tostring?view=net-10.0#system-convert-tostring(system-object-system-iformatprovider)

Content source URL

https://github.com/dotnet/dotnet-api-docs-temp/blob/live/xml/System/Convert.xml

Document Version Independent Id

1e8d70d8-4b6a-c39b-49d5-e383d1426584

Platform Id

f96e605a-bbd0-ccc4-bd41-87905b4fe2b1

Article author

@dotnet-bot

[gewarren]

I opened a PR to make some changes. The return values are actually different if you pass null directly vs. passing an object whose value is null, so the docs were already mostly correct. However, if you pass null directly, then the compiler actually calls the overload that takes a string, not an object. In the following code, c is null and c2 is the empty string.

[inosik]

Yes, the ToString(string) overload just returns the given string. If that happens to be null, the method returns null. The different overload resolution was a bit confusing when I was verifying the behavior of the method.

---

If value is null, the method returns null.

This part doesn't apply to the ToString(object, IFormatProvider) overload and should be removed, as your PR does 👍