string.Join with only null values returns delimiters instead of string.Empty

[3Mydlo3]

Description

According to string.Join(char, params string[]) method description:

Returns:
A string that consists of the elements of value delimited by the separator character. -or- string.Empty if value has zero elements or all the elements of value are null.

It should return string.Empty when all values are null. Well it does not, it returns string containing only the separator(s).

var values = new string[] { null, null, null };
var result1 = string.Join(';', values); // result1 = ";;"
var result2 = string.Join(';', null, null, null); // result2 = ";;"

var result3 = string.Join(";", values); // result3 = ";;"
var result4 = string.Join(";", null, null, null); // result4 = ";;"

It works the same for string.Join(string, params string[]) although its description does not mention case when all the elements of value are null:

Returns:
A string that consists of the elements in value delimited by the separator string. If value if an empty array, the method returns string.Empty.

Descriptions on MSDN are also inconsistent, where only Join(String, Object[]) and Join(String, String[]) do not have all the elements of values are null mentioned.

I do not know how this should be handled, probably adjusting descriptions to match current behaviour is the most reasonable way to handle this but maybe it worked at some point and behaviour should be fixed.

Configuration

First found on .NET Core 3.1.
Windows 10 Professional x64

Regression?

string.Join(char, params string[])
Tested with .NET Core 2.0, 3.0, 3.1

string.Join(string, params string[])
Tested with .NET Core 2.0, 3.0, 3.1 and .NET Framework 4.6, 4.7.2.

[GrabYourPitchforks]

I think this is a doc issue. Seems like the clause or all the elements of value are null should be nixed from the "Returns" section of the doc.

[GrabYourPitchforks]

Confirmed - not a regression from .NET Framework. I'll move this to the docs repo.

[Dotnet-GitSync-Bot]

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[GrabYourPitchforks]

Docs repo:

Request is to remove the bolded text below from https://docs.microsoft.com/dotnet/api/system.string.join.

Returns

String
A string that consists of the elements of value delimited by the separator character.

-or-

Empty if value has zero elements or all the elements of value are null.

[oskarb]

It seems like this trivial matter should have been resolved by now, it's been five years. Just forgotten?

[oskarb]

Although, a version of string.join() that does skip null (and optionally empty) elements (without adding separators) would be very nice, e.g. to avoid a leading or trailing garbage whitespace if either name is null or empty:

string displayName = string.join(SkipEmpty, " ", firstname, lastname);