From 6b8088dd2eb0023a37ad035517b4d0a0b2b55602 Mon Sep 17 00:00:00 2001
From: Smaug123 <3138005+Smaug123@users.noreply.github.com>
Date: Sat, 19 Jul 2025 08:14:23 +0100
Subject: [PATCH] Add info about failure modes to ConcurrentQueue Try methods

---
 xml/System.Collections.Concurrent/ConcurrentQueue`1.xml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/xml/System.Collections.Concurrent/ConcurrentQueue`1.xml b/xml/System.Collections.Concurrent/ConcurrentQueue`1.xml
index dfc4bbb74c3..69c7a3a2d8b 100644
--- a/xml/System.Collections.Concurrent/ConcurrentQueue`1.xml
+++ b/xml/System.Collections.Concurrent/ConcurrentQueue`1.xml
@@ -551,7 +551,7 @@
         <param name="item">The object to add to the <see cref="T:System.Collections.Concurrent.IProducerConsumerCollection`1" />. The value can be a null reference (Nothing in Visual Basic) for reference types.</param>
         <summary>Attempts to add an object to the <see cref="T:System.Collections.Concurrent.IProducerConsumerCollection`1" />.</summary>
         <returns>
-          <see langword="true" /> if the object was added successfully; otherwise, <see langword="false" />.</returns>
+          <see langword="true" /> if the object was added successfully; otherwise, <see langword="false" />. (This operation never returns <see langword="false" /> for <xref cref="System.Collections.Concurrent.ConcurrentQueue`1"/>.)</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[  
   
@@ -614,7 +614,7 @@
         <param name="item">When this method returns, if the operation was successful, <paramref name="item" /> contains the object removed. If no object was available to be removed, the value is unspecified.</param>
         <summary>Attempts to remove and return an object from the <see cref="T:System.Collections.Concurrent.IProducerConsumerCollection`1" />.</summary>
         <returns>
-          <see langword="true" /> if an element was removed and returned successfully; otherwise, <see langword="false" />.</returns>
+          <see langword="true" /> if an element was removed and returned successfully; otherwise, <see langword="false" /> (that is, if there were no elements in the queue at the instant the call tried to take an element).</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[  
   
@@ -932,7 +932,7 @@ This member is an explicit interface member implementation. It can be used only
         <param name="result">When this method returns, if the operation was successful, <paramref name="result" /> contains the object removed. If no object was available to be removed, the value is unspecified.</param>
         <summary>Tries to remove and return the object at the beginning of the concurrent queue.</summary>
         <returns>
-          <see langword="true" /> if an element was removed and returned from the beginning of the <see cref="T:System.Collections.Concurrent.ConcurrentQueue`1" /> successfully; otherwise, <see langword="false" />.</returns>
+          <see langword="true" /> if an element was removed and returned from the beginning of the <see cref="T:System.Collections.Concurrent.ConcurrentQueue`1" /> successfully; otherwise, <see langword="false" /> (that is, if there were no elements in the queue at the instant the call tried to dequeue).</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[  
   
@@ -994,7 +994,7 @@ This member is an explicit interface member implementation. It can be used only
         <param name="result">When this method returns, <paramref name="result" /> contains an object from the beginning of the <see cref="T:System.Collections.Concurrent.ConcurrentQueue`1" /> or an unspecified value if the operation failed.</param>
         <summary>Tries to return an object from the beginning of the <see cref="T:System.Collections.Concurrent.ConcurrentQueue`1" /> without removing it.</summary>
         <returns>
-          <see langword="true" /> if an object was returned successfully; otherwise, <see langword="false" />.</returns>
+          <see langword="true" /> if an object was returned successfully; otherwise, <see langword="false" /> (that is, if there were no elements in the queue at the instant the call tried to peek).</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[