Documentation: Fixes change feed estimator remarks (#3000)

* container docs

* cf pull docs

Microsoft.Azure.Cosmos/src/ChangeFeedProcessor/ChangeFeedEstimator.cs

@@ -18,7 +18,11 @@ public abstract class ChangeFeedEstimator
         /// Gets the estimation per lease in the lease container.
         /// </summary>
         /// <param name="changeFeedEstimatorRequestOptions">(Optional) Customize the estimation iterator.</param>
-        /// <returns>An iterator that yields an estimation of pending work in amount of documents per distributed lease token.</returns>
+        /// <returns>An iterator that yields an estimation of pending work in amount of transactions per distributed lease token.</returns>
+        /// <remarks>
+        /// The estimation over the Change Feed identifies volumes of transactions. If operations in the container are performed through stored procedures, transactional batch or bulk, a group of operations may share the same <see href="https://docs.microsoft.com/azure/cosmos-db/stored-procedures-triggers-udfs#transactions">transaction scope</see> and represented by a single transaction. 
+        /// In those cases, the estimation might not exactly represent number of items, but it is still valid to understand if the pending volume is increasing, decreasing, or on a steady state.
+        /// </remarks>
         public abstract FeedIterator<ChangeFeedProcessorState> GetCurrentStateIterator(ChangeFeedEstimatorRequestOptions changeFeedEstimatorRequestOptions = null);
     }
 }

Microsoft.Azure.Cosmos/src/ChangeFeedProcessor/ChangeFeedProcessorState.cs

@@ -33,8 +33,12 @@ public sealed class ChangeFeedProcessorState
         public string LeaseToken { get; }
 
         /// <summary>
-        /// Gets an approximation of the difference between the last processed item in the feed container and the latest change recorded.
+        /// Gets an approximation of the difference between the last processed transaction in the feed container and the latest transaction recorded.
         /// </summary>
+        /// <remarks>
+        /// The estimation over the Change Feed identifies volumes of transactions. If operations in the container are performed through stored procedures, transactional batch or bulk, a group of operations may share the same <see href="https://docs.microsoft.com/azure/cosmos-db/stored-procedures-triggers-udfs#transactions">transaction scope</see> and represented by a single transaction. 
+        /// In those cases, the estimation might not exactly represent number of items, but it is still valid to understand if the pending volume is increasing, decreasing, or on a steady state.
+        /// </remarks>
         public long EstimatedLag { get; }
 
         /// <summary>

Microsoft.Azure.Cosmos/src/Resource/Container/Container.cs

@@ -1177,10 +1177,13 @@ public abstract class Container
         /// <summary>
         /// Delegate to receive the estimation of pending changes to be read by the associated <see cref="ChangeFeedProcessor"/> instance.
         /// </summary>
-        /// <param name="estimatedPendingChanges">An estimation in number of items.</param>
+        /// <param name="estimatedPendingChanges">An estimation in number of transactions.</param>
         /// <param name="cancellationToken">A cancellation token representing the current cancellation status of the <see cref="ChangeFeedProcessor"/> instance.</param>
         /// <returns>A <see cref="Task"/> representing the asynchronous operation that is going to be done with the estimation.</returns>
-        /// <exception>https://aka.ms/cosmosdb-dot-net-exceptions#typed-api</exception>
+        /// <remarks>
+        /// The estimation over the Change Feed identifies volumes of transactions. If operations in the container are performed through stored procedures, transactional batch or bulk, a group of operations may share the same <see href="https://docs.microsoft.com/azure/cosmos-db/stored-procedures-triggers-udfs#transactions">transaction scope</see> and represented by a single transaction. 
+        /// In those cases, the estimation might not exactly represent number of items, but it is still valid to understand if the pending volume is increasing, decreasing, or on a steady state.
+        /// </remarks>
         public delegate Task ChangesEstimationHandler(
             long estimatedPendingChanges,
             CancellationToken cancellationToken);