Update Semaphore.xml (#3810)

* Update Semaphore.xml

Added detailed description to the name parameters, explaining the 4 possibilities (prefix with "Global\", prefix with "Local\", name without prefix, null or empty string).

* Apply suggestions from code review

Co-authored-by: Koundinya Veluri <[email protected]>

Co-authored-by: Genevieve Warren <[email protected]>
Co-authored-by: Koundinya Veluri <[email protected]>

Author: 3 people

xml/System.Threading/Semaphore.xml

@@ -199,7 +199,7 @@
       <Docs>
         <param name="initialCount">The initial number of requests for the semaphore that can be granted concurrently.</param>
         <param name="maximumCount">The maximum number of requests for the semaphore that can be granted concurrently.</param>
-        <param name="name">The name of a named system semaphore object.</param>
+        <param name="name">The name of the semaphore. If it is <see langword="null" /> or empty, a process-local semaphore is created. If the name is prefixed by "Global\", a machine-wide semaphore is created (or the existing one returned). If it is prefixed by "Local\", a session-wide semaphore is created (or the existing one returned). If the name is not prefixed at all, a session-wide semaphore is created (same as prefix "Local\"). Both prefix and name are case-sensitive.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Threading.Semaphore" /> class, specifying the initial number of entries and the maximum number of concurrent entries, and optionally specifying the name of a system semaphore object.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[  
@@ -291,7 +291,7 @@
       <Docs>
         <param name="initialCount">The initial number of requests for the semaphore that can be satisfied concurrently.</param>
         <param name="maximumCount">The maximum number of requests for the semaphore that can be satisfied concurrently.</param>
-        <param name="name">The name of a named system semaphore object.</param>
+        <param name="name">The name of the semaphore. If it is <see langword="null" /> or empty, a process-local semaphore is created. If the name is prefixed by "Global\", a machine-wide semaphore is created (or the existing one returned). If it is prefixed by "Local\", a session-wide semaphore is created (or the existing one returned). If the name is not prefixed at all, a session-wide semaphore is created (same as prefix "Local\"). Both prefix and name are case-sensitive.</param>
         <param name="createdNew">When this method returns, contains <see langword="true" /> if a local semaphore was created (that is, if <paramref name="name" /> is <see langword="null" /> or an empty string) or if the specified named system semaphore was created; <see langword="false" /> if the specified named system semaphore already existed. This parameter is passed uninitialized.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Threading.Semaphore" /> class, specifying the initial number of entries and the maximum number of concurrent entries, optionally specifying the name of a system semaphore object, and specifying a variable that receives a value indicating whether a new system semaphore was created.</summary>
         <remarks>
@@ -368,7 +368,7 @@
       <Docs>
         <param name="initialCount">The initial number of requests for the semaphore that can be satisfied concurrently.</param>
         <param name="maximumCount">The maximum number of requests for the semaphore that can be satisfied concurrently.</param>
-        <param name="name">The name of a named system semaphore object.</param>
+        <param name="name">The name of the semaphore. If it is <see langword="null" /> or empty, a process-local semaphore is created. If the name is prefixed by "Global\", a machine-wide semaphore is created (or the existing one returned). If it is prefixed by "Local\", a session-wide semaphore is created (or the existing one returned). If the name is not prefixed at all, a session-wide semaphore is created (same as prefix "Local\"). Both prefix and name are case-sensitive.</param>
         <param name="createdNew">When this method returns, contains <see langword="true" /> if a local semaphore was created (that is, if <paramref name="name" /> is <see langword="null" /> or an empty string) or if the specified named system semaphore was created; <see langword="false" /> if the specified named system semaphore already existed. This parameter is passed uninitialized.</param>
         <param name="semaphoreSecurity">A <see cref="T:System.Security.AccessControl.SemaphoreSecurity" /> object that represents the access control security to be applied to the named system semaphore.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Threading.Semaphore" /> class, specifying the initial number of entries and the maximum number of concurrent entries, optionally specifying the name of a system semaphore object, specifying a variable that receives a value indicating whether a new system semaphore was created, and specifying security access control for the system semaphore.</summary>
@@ -545,7 +545,7 @@
         <Parameter Name="name" Type="System.String" />
       </Parameters>
       <Docs>
-        <param name="name">The name of the system semaphore to open.</param>
+        <param name="name">The name of the semaphore. If it's prefixed by "Global\", it refers to a machine-wide semaphore. If it's prefixed by "Local\" or doesn't have a prefix, it refers to a session-wide semaphore. Both prefix and name are case-sensitive.</param>
         <summary>Opens the specified named semaphore, if it already exists.</summary>
         <returns>An object that represents the named system semaphore.</returns>
         <remarks>
@@ -620,7 +620,7 @@
         <Parameter Name="rights" Type="System.Security.AccessControl.SemaphoreRights" Index="1" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0" />
       </Parameters>
       <Docs>
-        <param name="name">The name of the system semaphore to open.</param>
+        <param name="name">The name of the semaphore. If it's prefixed by "Global\", it refers to a machine-wide semaphore. If it's prefixed by "Local\" or doesn't have a prefix, it refers to a session-wide semaphore. Both prefix and name are case-sensitive.</param>
         <param name="rights">A bitwise combination of the enumeration values that represent the desired security access.</param>
         <summary>Opens the specified named semaphore, if it already exists, with the desired security access.</summary>
         <returns>An object that represents the named system semaphore.</returns>
@@ -959,7 +959,7 @@
         <Parameter Name="result" Type="System.Threading.Semaphore" RefType="out" Index="1" FrameworkAlternate="dotnet-uwp-10.0;net-5.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.6;netstandard-2.0;netstandard-2.1;xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0" />
       </Parameters>
       <Docs>
-        <param name="name">The name of the system semaphore to open.</param>
+        <param name="name">The name of the semaphore. If it's prefixed by "Global\", it refers to a machine-wide semaphore. If it's prefixed by "Local\" or doesn't have a prefix, it refers to a session-wide semaphore. Both prefix and name are case-sensitive.</param>
         <param name="result">When this method returns, contains a <see cref="T:System.Threading.Semaphore" /> object that represents the named semaphore if the call succeeded, or <see langword="null" /> if the call failed. This parameter is treated as uninitialized.</param>
         <summary>Opens the specified named semaphore, if it already exists, and returns a value that indicates whether the operation succeeded.</summary>
         <returns>
@@ -1016,7 +1016,7 @@
         <Parameter Name="result" Type="System.Threading.Semaphore" RefType="out" Index="2" FrameworkAlternate="netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0" />
       </Parameters>
       <Docs>
-        <param name="name">The name of the system semaphore to open.</param>
+        <param name="name">The name of the semaphore. If it's prefixed by "Global\", it refers to a machine-wide semaphore. If it's prefixed by "Local\" or doesn't have a prefix, it refers to a session-wide semaphore. Both prefix and name are case-sensitive.</param>
         <param name="rights">A bitwise combination of the enumeration values that represent the desired security access.</param>
         <param name="result">When this method returns, contains a <see cref="T:System.Threading.Semaphore" /> object that represents the named semaphore if the call succeeded, or <see langword="null" /> if the call failed. This parameter is treated as uninitialized.</param>
         <summary>Opens the specified named semaphore, if it already exists, with the desired security access, and returns a value that indicates whether the operation succeeded.</summary>