docs: Clarify the use of FlowControlSettings in SusbcriberClient.

apis/Google.Cloud.PubSub.V1/Google.Cloud.PubSub.V1/SubscriberClient.Settings.cs

@@ -27,8 +27,29 @@ public sealed class Settings
     {
         /// <summary>
         /// Flow control settings.
-        /// If <c>null</c>, uses flow control settings from <see cref="DefaultFlowControlSettings"/>. 
+        /// If <c>null</c>, uses flow control settings from <see cref="DefaultFlowControlSettings"/>.
         /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Flow control uses these settings for two purposes: fetching messages to process, and processing them.
+        /// </para>
+        /// <para>
+        /// In terms of fetching messages, a single <see cref="SubscriberClient"/> creates multiple instances of
+        /// <see cref="SubscriberServiceApiClient"/>, and each will observe the flow control settings independently.
+        /// This means there may be more outstanding messages (or bytes) than expected; there is currently no way
+        /// of limiting the total number or size of outstanding messages fetched across all data streams for a single
+        /// <see cref="SubscriberClient"/>.
+        /// </para>
+        /// <para>
+        /// Separately, the number of messages being processed concurrently is limited by these settings, at
+        /// the level of the whole <see cref="SubscriberClient"/>.
+        /// </para>
+        /// <para>
+        /// For example, if <see cref="FlowControlSettings.MaxOutstandingElementCount"/> is set to 10, then a single
+        /// <see cref="SubscriberClient"/> using 4 instances of <see cref="SubscriberServiceApiClient"/> will have up
+        /// to 40 outstanding messages to process, but will only process at most 10 of them concurrently.
+        /// </para>
+        /// </remarks>
         public FlowControlSettings FlowControlSettings { get; set; }
 
         /// <summary>