Documentation: Fixes change feed estimator remarks

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 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 delegate Task ChangesHandler<T>(
  /// <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);