Improve return value descriptions of String.Join

Author: ssimek

xml/System/String.xml

@@ -8373,7 +8373,7 @@ A string is empty if it  is explicitly assigned an empty string ("") or <xref:Sy
 
 -or-
 
-<see cref="F:System.String.Empty" /> if <paramref name="values" /> has zero elements or all the elements of <paramref name="values" /> are <see langword="null" />.</returns>
+<see cref="F:System.String.Empty" /> if <paramref name="values" /> has zero elements.</returns>
         <remarks>To be added.</remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="value" /> is <see langword="null" />.</exception>
@@ -8424,7 +8424,7 @@ A string is empty if it  is explicitly assigned an empty string ("") or <xref:Sy
 
 -or-
 
-<see cref="F:System.String.Empty" /> if <paramref name="value" /> has zero elements or all the elements of <paramref name="value" /> are <see langword="null" />.</returns>
+<see cref="F:System.String.Empty" /> if <paramref name="value" /> has zero elements.</returns>
         <remarks>To be added.</remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="value" /> is <see langword="null" />.</exception>
@@ -8478,11 +8478,11 @@ A string is empty if it  is explicitly assigned an empty string ("") or <xref:Sy
         <param name="separator">The string to use as a separator.<paramref name="separator" /> is included in the returned string only if <paramref name="values" /> has more than one element.</param>
         <param name="values">A collection that contains the strings to concatenate.</param>
         <summary>Concatenates the members of a constructed <see cref="T:System.Collections.Generic.IEnumerable`1" /> collection of type <see cref="T:System.String" />, using the specified separator between each member.</summary>
-        <returns>A string that consists of the members of <paramref name="values" /> delimited by the <paramref name="separator" /> string.
+        <returns>A string that consists of the elements of <paramref name="values" /> delimited by the <paramref name="separator" /> string.
 
 -or-
 
-<see cref="F:System.String.Empty" /> if <paramref name="values" /> has zero elements or all the elements of <paramref name="values" /> are <see langword="null" />.</returns>
+<see cref="F:System.String.Empty" /> if <paramref name="values" /> has zero elements.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -8562,7 +8562,15 @@ A string is empty if it  is explicitly assigned an empty string ("") or <xref:Sy
         <param name="separator">The string to use as a separator. <paramref name="separator" /> is included in the returned string only if <paramref name="values" /> has more than one element.</param>
         <param name="values">An array that contains the elements to concatenate.</param>
         <summary>Concatenates the elements of an object array, using the specified separator between each element.</summary>
-        <returns>A string that consists of the elements of <paramref name="values" /> delimited by the <paramref name="separator" /> string. If <paramref name="values" /> is an empty array, the method returns <see cref="F:System.String.Empty" />.</returns>
+        <returns>A string that consists of the elements of <paramref name="values" /> delimited by the <paramref name="separator" /> string.
+
+-or-
+
+<see cref="F:System.String.Empty" /> if <paramref name="values" /> has zero elements.
+
+-or-
+
+.NET Framework only: <see cref="F:System.String.Empty" /> if the first element of <paramref name="values" /> is <see langword="null" />.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -8585,7 +8593,7 @@ A string is empty if it  is explicitly assigned an empty string ("") or <xref:Sy
           <paramref name="values" /> is <see langword="null" />.</exception>
         <exception cref="T:System.OutOfMemoryException">The length of the resulting string overflows the maximum allowed length (<see cref="F:System.Int32.MaxValue" />).</exception>
         <block subset="none" type="usage">
-          <para>If the first element of <paramref name="values" /> is <see langword="null" />, the <see cref="M:System.String.Join(System.String,System.Object[])" /> method does not concatenate the elements in <paramref name="values" /> but instead returns <see cref="F:System.String.Empty" />. A number of workarounds for this issue are available. The easiest is to assign a value of <see cref="F:System.String.Empty" /> to the first element of the array, as the following example shows.
+          <para>.NET Framework only: If the first element of <paramref name="values" /> is <see langword="null" />, the <see cref="M:System.String.Join(System.String,System.Object[])" /> method does not concatenate the elements in <paramref name="values" /> but instead returns <see cref="F:System.String.Empty" />. A number of workarounds for this issue are available. The easiest is to assign a value of <see cref="F:System.String.Empty" /> to the first element of the array, as the following example shows.
 
  [!code-csharp-interactive[System.String.Join#6](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.join/cs/joinfix1.cs#6)]
  [!code-vb[System.String.Join#6](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/joinfix1.vb#6)]</para>
@@ -8646,7 +8654,11 @@ A string is empty if it  is explicitly assigned an empty string ("") or <xref:Sy
         <param name="separator">The string to use as a separator. <paramref name="separator" /> is included in the returned string only if <paramref name="value" /> has more than one element.</param>
         <param name="value">An array that contains the elements to concatenate.</param>
         <summary>Concatenates all the elements of a string array, using the specified separator between each element.</summary>
-        <returns>A string that consists of the elements in <paramref name="value" /> delimited by the <paramref name="separator" /> string. If <paramref name="value" /> is an empty array, the method returns <see cref="F:System.String.Empty" />.</returns>
+        <returns>A string that consists of the elements in <paramref name="value" /> delimited by the <paramref name="separator" /> string.
+
+-or-
+
+<see cref="F:System.String.Empty" /> if <paramref name="values" /> has zero elements.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -8710,11 +8722,11 @@ A string is empty if it  is explicitly assigned an empty string ("") or <xref:Sy
         <param name="startIndex">The first item in <paramref name="value" /> to concatenate.</param>
         <param name="count">The number of elements from <paramref name="value" /> to concatenate, starting with the element in the <paramref name="startIndex" /> position.</param>
         <summary>Concatenates an array of strings, using the specified separator between each member, starting with the element in <paramref name="value" /> located at the <paramref name="startIndex" /> position, and concatenating up to <paramref name="count" /> elements.</summary>
-        <returns>A string that consists of the elements of <paramref name="value" /> delimited by the <paramref name="separator" /> character.
+        <returns>A string that consists of <paramref name="count" /> elements of <paramref name="value" /> starting at <paramref name="startIndex" /> delimited by the <paramref name="separator" /> character.
 
 -or-
 
-<see cref="F:System.String.Empty" /> if <paramref name="count" /> is zero, <paramref name="value" /> has no elements, or all the elements of <paramref name="value" /> are <see langword="null" /> or <see cref="F:System.String.Empty" />.</returns>
+<see cref="F:System.String.Empty" /> if <paramref name="count" /> is zero.</returns>
         <remarks>To be added.</remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="value" /> is <see langword="null" />.</exception>
@@ -8780,11 +8792,11 @@ A string is empty if it  is explicitly assigned an empty string ("") or <xref:Sy
         <param name="startIndex">The first element in <paramref name="value" /> to use.</param>
         <param name="count">The number of elements of <paramref name="value" /> to use.</param>
         <summary>Concatenates the specified elements of a string array, using the specified separator between each element.</summary>
-        <returns>A string that consists of the strings in <paramref name="value" /> delimited by the <paramref name="separator" /> string.
+        <returns>A string that consists of <paramref name="count" /> elements of <paramref name="value" /> starting at <paramref name="startIndex" /> delimited by the <paramref name="separator" /> character.
 
  -or-
 
- <see cref="F:System.String.Empty" /> if <paramref name="count" /> is zero, <paramref name="value" /> has no elements, or <paramref name="separator" /> and all the elements of <paramref name="value" /> are <see cref="F:System.String.Empty" />.</returns>
+ <see cref="F:System.String.Empty" /> if <paramref name="count" /> is zero.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -8853,7 +8865,11 @@ A string is empty if it  is explicitly assigned an empty string ("") or <xref:Sy
         <param name="separator">The character to use as a separator. <paramref name="separator" /> is included in the returned string only if <paramref name="values" /> has more than one element.</param>
         <param name="values">A collection that contains the objects to concatenate.</param>
         <summary>Concatenates the members of a collection, using the specified separator between each member.</summary>
-        <returns>A string that consists of the members of <paramref name="values" /> delimited by the <paramref name="separator" /> character. If <paramref name="values" /> has no members, the method returns <see cref="F:System.String.Empty" />.</returns>
+        <returns>A string that consists of the members of <paramref name="values" /> delimited by the <paramref name="separator" /> character.
+
+-or-
+
+<see cref="F:System.String.Empty" /> if <paramref name="values" /> has no elements.</returns>
         <remarks>To be added.</remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="values" /> is <see langword="null" />.</exception>
@@ -8911,7 +8927,11 @@ A string is empty if it  is explicitly assigned an empty string ("") or <xref:Sy
         <param name="separator">The string to use as a separator. <paramref name="separator" /> is included in the returned string only if <paramref name="values" /> has more than one element.</param>
         <param name="values">A collection that contains the objects to concatenate.</param>
         <summary>Concatenates the members of a collection, using the specified separator between each member.</summary>
-        <returns>A string that consists of the members of <paramref name="values" /> delimited by the <paramref name="separator" /> string. If <paramref name="values" /> has no members, the method returns <see cref="F:System.String.Empty" />.</returns>
+        <returns>A string that consists of the elements of <paramref name="values" /> delimited by the <paramref name="separator" /> string.
+
+-or-
+
+<see cref="F:System.String.Empty" /> if <paramref name="values" /> has no elements.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[