RavenDB-22637 : xml documentation for various Counters and TimeSeries…

… operations, and for several Include Builders

src/Raven.Client/Documents/Operations/Counters/CounterBatch.cs

@@ -7,13 +7,19 @@
 
 namespace Raven.Client.Documents.Operations.Counters
 {
+    /// <summary>
+    /// Represents a batch of counter operations on multiple documents, supporting retrieval of counter values across nodes.
+    /// </summary>
     public sealed class CounterBatch
     {
         public bool ReplyWithAllNodesValues;
         public List<DocumentCountersOperation> Documents = new List<DocumentCountersOperation>();
         public bool FromEtl;
     }
 
+    /// <summary>
+    /// Represents counter operations for a specific document, such as increment or set operations on named counters.
+    /// </summary>
     public sealed class DocumentCountersOperation
     {
         public List<CounterOperation> Operations;
@@ -82,6 +88,9 @@ public enum CounterOperationType
         GetAll
     }
 
+    /// <summary>
+    /// Represents a single counter operation, which defines actions such as incrementing a counter value, deleting a counter or retrieving a counter value for a specific document and counter name.
+    /// </summary>
     public sealed class CounterOperation
     {
         public CounterOperationType Type;

src/Raven.Client/Documents/Operations/Counters/CounterBatchOperation.cs

@@ -12,6 +12,10 @@ public sealed class CounterBatchOperation : IOperation<CountersDetail>
     {
         private readonly CounterBatch _counterBatch;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CounterBatchOperation"/> class with the specified counter batch.
+        /// </summary>
+        /// <param name="counterBatch">The batch of counter operations to be processed.</param>
         public CounterBatchOperation(CounterBatch counterBatch)
         {
             _counterBatch = counterBatch;

src/Raven.Client/Documents/Operations/Counters/GetCountersOperation.cs

@@ -16,20 +16,39 @@ public sealed class GetCountersOperation : IOperation<CountersDetail>
         private readonly string[] _counters;
         private readonly bool _returnFullResults;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GetCountersOperation"/> class with a specific document ID, 
+        /// an array of counter names, and a flag indicating whether to include counter values from each node in the result.
+        /// </summary>
+        /// <param name="docId">The ID of the document for which to retrieve counters.</param>
+        /// <param name="counters">An array of counter names to retrieve.</param>
+        /// <param name="returnFullResults">A value indicating whether the result should include counter values from each node.</param>
         public GetCountersOperation(string docId, string[] counters, bool returnFullResults = false)
         {
             _docId = docId;
             _counters = counters;
             _returnFullResults = returnFullResults;
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GetCountersOperation"/> class with a specific document ID 
+        /// and a single counter name, along with a flag indicating whether to include counter values from each node in the result.
+        /// </summary>
+        /// <inheritdoc cref="GetCountersOperation(string, string[], bool)"/>
+        /// <param name="counter">The name of the counter to retrieve.</param>
         public GetCountersOperation(string docId, string counter, bool returnFullResults = false)
         {
             _docId = docId;
             _counters = new[] { counter };
             _returnFullResults = returnFullResults;
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GetCountersOperation"/> class with a specific document ID 
+        /// and a flag indicating whether to include counter values from each node in the result.
+        /// This operation retrieves all counters associated with the given document.
+        /// </summary>
+        /// <inheritdoc cref="GetCountersOperation(string, string[], bool)"/>
         public GetCountersOperation(string docId, bool returnFullResults = false)
         {
             _docId = docId;

src/Raven.Client/Documents/Operations/TimeSeries/GetMultipleTimeSeriesOperation.cs

@@ -21,6 +21,18 @@ public sealed class GetMultipleTimeSeriesOperation : IOperation<TimeSeriesDetail
         private readonly Action<ITimeSeriesIncludeBuilder> _includes;
         private readonly bool _returnFullResults;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GetMultipleTimeSeriesOperation"/> class, 
+        /// retrieving entries from multiple time series associated with a document across specified ranges.
+        /// </summary>
+        /// <param name="docId">The ID of the document for which time series entries are requested.</param>
+        /// <param name="ranges">
+        /// A collection of <see cref="TimeSeriesRange"/> objects, each specifying a time series name 
+        /// and a date range (<c>from</c> and <c>to</c>) to retrieve entries from.
+        /// </param>
+        /// <param name="start">The start index for pagination of results.</param>
+        /// <param name="pageSize">The number of entries to retrieve. Defaults to <c>int.MaxValue</c> for all entries.</param>
+        /// <param name="returnFullResults">Whether to include detailed information for each entry. If <c>false</c>, retrieves only basic information.</param>
         public GetMultipleTimeSeriesOperation(string docId, IEnumerable<TimeSeriesRange> ranges, int start = 0, int pageSize = int.MaxValue, bool returnFullResults = false)
             : this(docId, ranges, start, pageSize, includes: null, returnFullResults)
         {

src/Raven.Client/Documents/Operations/TimeSeries/GetTimeSeriesOperation.cs

@@ -14,11 +14,17 @@ namespace Raven.Client.Documents.Operations.TimeSeries
 {
     public sealed class GetTimeSeriesOperation : GetTimeSeriesOperation<TimeSeriesEntry>
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GetTimeSeriesOperation"/> class, 
+        /// retrieving multiple entries from a time series associated with a document within a specified date range.
+        /// </summary>
+        /// <inheritdoc select="param" />
         public GetTimeSeriesOperation(string docId, string timeseries, DateTime? @from = null, DateTime? to = null, int start = 0, int pageSize = int.MaxValue, bool returnFullResults = false) : base(docId, timeseries, @from, to, start, pageSize, returnFullResults)
         {
         }
     }
 
+
     public class GetTimeSeriesOperation<TValues> : IOperation<TimeSeriesRangeResult<TValues>> where TValues : TimeSeriesEntry
     {
         private readonly string _docId, _name;
@@ -27,6 +33,21 @@ public class GetTimeSeriesOperation<TValues> : IOperation<TimeSeriesRangeResult<
         private readonly Action<ITimeSeriesIncludeBuilder> _includes;
         private readonly bool _returnFullResults;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GetTimeSeriesOperation{TValues}"/> class, 
+        /// retrieving multiple entries from a time series associated with a document within a specified date range.
+        /// </summary>
+        /// <typeparam name="TValues">
+        /// The type to which each time series entry should be projected. 
+        /// Must be a subtype of <see cref="TimeSeriesEntry"/>.
+        /// </typeparam>
+        /// <param name="docId">The ID of the document that holds the time series.</param>
+        /// <param name="timeseries">The name of the time series to retrieve.</param>
+        /// <param name="from">The start date of the range from which entries should be retrieved. If <c>null</c>, retrieval begins from the earliest entry.</param>
+        /// <param name="to">The end date of the range up to which entries should be retrieved. If <c>null</c>, retrieval continues to the latest entry.</param>
+        /// <param name="start">The start index for pagination of results.</param>
+        /// <param name="pageSize">The number of entries to retrieve. Defaults to <c>int.MaxValue</c> for retrieving all entries within the specified range.</param>
+        /// <param name="returnFullResults">Whether to include detailed information for each entry. If <c>false</c>, retrieves only basic information.</param>
         public GetTimeSeriesOperation(string docId, string timeseries, DateTime? from = null, DateTime? to = null, int start = 0, int pageSize = int.MaxValue, bool returnFullResults = false) 
             : this(docId, timeseries, from, to, start, pageSize, includes: null, returnFullResults)
         { }

src/Raven.Client/Documents/Operations/TimeSeries/TimeSeriesBatchOperation.cs

@@ -12,6 +12,12 @@ public sealed class TimeSeriesBatchOperation : IOperation
         private readonly string _documentId;
         private readonly TimeSeriesOperation _operation;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="TimeSeriesBatchOperation"/> class, 
+        /// performing batch operations on a time series, including appending or deleting entries.
+        /// </summary>
+        /// <param name="documentId">The ID of the document that holds the time series.</param>
+        /// <param name="operation">The batch of time series operations to be applied.</param>
         public TimeSeriesBatchOperation(string documentId, TimeSeriesOperation operation)
         {
             _documentId = documentId ?? throw new ArgumentNullException(nameof(documentId));

src/Raven.Client/Documents/Operations/TimeSeries/TimeSeriesOperation.cs

@@ -8,6 +8,10 @@
 
 namespace Raven.Client.Documents.Operations.TimeSeries
 {
+    /// <summary>
+    /// Represents a batch operation for time series data, including appends, increments, and deletions, 
+    /// to be performed on a single document’s time series.
+    /// </summary>
     public sealed class TimeSeriesOperation
     {
         private SortedList<long, AppendOperation> _appends;
@@ -291,6 +295,9 @@ public DynamicJsonValue ToJson()
             };
         }
 
+        /// <summary>
+        /// Represents an append operation in a time series, allowing new data points to be added at specific timestamps.
+        /// </summary>
         public sealed class AppendOperation
         {
             public DateTime Timestamp;
@@ -338,6 +345,9 @@ public DynamicJsonValue ToJson()
             }
         }
 
+        /// <summary>
+        /// Represents a delete operation in a time series, allowing data points within a specific range to be removed.
+        /// </summary>
         public sealed class DeleteOperation
         {
             public DateTime? From, To;
@@ -364,6 +374,9 @@ public DynamicJsonValue ToJson()
             }
         }
 
+        /// <summary>
+        /// Represents an increment operation in a time series, allowing values at a specific timestamp to be incremented.
+        /// </summary>
         public sealed class IncrementOperation
         {
             public DateTime Timestamp;

src/Raven.Client/Documents/Session/Loaders/IncludeBuilder.cs

@@ -115,10 +115,36 @@ public interface IAbstractTimeSeriesIncludeBuilder<T, out TBuilder>
         TBuilder IncludeAllTimeSeries(TimeSeriesRangeType type, int count);
     }
 
+    /// <summary>
+    /// The server is instructed to include revisions of the specified documents when retrieving them.<br/>
+    /// Once loaded into the session, revisions can be accessed without additional server requests, ensuring efficient 
+    /// retrieval of document history.
+    /// </summary>
     public interface IRevisionIncludeBuilder<T, out TBuilder> 
     {
+        /// <summary>
+        /// Include a single revision by specifying the path to the document property that contains the revision's change vector.
+        /// Each time a document is modified, its change vector is updated. By storing the change vector in a dedicated 
+        /// property, you can easily include revisions when the document is loaded.
+        /// </summary>
+        /// <param name="path">An expression indicating the property path containing the revision change vector.</param>
         TBuilder IncludeRevisions(Expression<Func<T, string>> path);
+
+        /// <summary>
+        /// Include multiple revisions by specifying the path to the document property that contains an array of change vectors.
+        /// When modifications are made to the document, the updated change vectors can be stored, allowing you to easily
+        /// include multiple revisions when the document is loaded.
+        /// </summary>
+        /// <param name="path">An expression indicating the property path containing the revision change vectors.</param>
         TBuilder IncludeRevisions(Expression<Func<T, IEnumerable<string>>> path);
+
+        /// <summary>
+        /// Include a single revision by specifying its creation time. 
+        /// The specified time can be in local time or UTC; the server will convert it to UTC.
+        /// If an exact match for the creation time is found, that revision will be included. 
+        /// Otherwise, the first revision preceding the specified time will be returned.
+        /// </summary>
+        /// <param name="before">The creation time of the revision to include.</param>
         TBuilder IncludeRevisions(DateTime before);
 
     }
@@ -137,16 +163,46 @@ public interface ISubscriptionTimeSeriesIncludeBuilder<T, out TBuilder> : IAbstr
     {
     }
 
+    /// <summary>
+    /// The server is instructed to include Compare Exchange values when retrieving documents.<br/>
+    /// Compare Exchange items can be included both when loading entities and during query execution. 
+    /// The session automatically tracks the included Compare Exchange items, allowing their values 
+    /// to be accessed without making additional calls to the server.
+    /// </summary>
     public interface ICompareExchangeValueIncludeBuilder<T, out TBuilder>
     {
+        /// <summary>
+        /// Include a single Compare Exchange value by specifying its key.
+        /// The key should correspond to the Compare Exchange item you wish to include.
+        /// </summary>
+        /// <param name="path">The key of the Compare Exchange value to include.</param>
         TBuilder IncludeCompareExchangeValue(string path);
 
+        /// <summary>
+        /// Include a single Compare Exchange value by specifying a path to the key.
+        /// This allows for dynamic resolution of the Compare Exchange key based on 
+        /// the document's properties.
+        /// </summary>
+        /// <param name="path">An expression indicating the property path that resolves to the Compare Exchange key.</param>
         TBuilder IncludeCompareExchangeValue(Expression<Func<T, string>> path);
 
+        /// <summary>
+        /// Include multiple Compare Exchange values by specifying a path to a collection of keys.
+        /// This allows for the inclusion of multiple Compare Exchange items in a single call.
+        /// </summary>
+        /// <param name="path">An expression indicating the property path that resolves to an array of Compare Exchange keys.</param>
         TBuilder IncludeCompareExchangeValue(Expression<Func<T, IEnumerable<string>>> path);
 
     }
 
+    /// <summary>
+    /// The server is instructed to include various types of related items when retrieving documents.<br/>
+    /// The items are added to the session unit of work, and subsequent requests to load them are served directly from the session cache,
+    /// without requiring any additional queries to the server.
+    /// This interface combines functionalities for including documents, counters, time series, compare exchange values, and revisions.
+    /// </summary>
+    /// <typeparam name="T">The type of the document being built.</typeparam>
+    /// <typeparam name="TBuilder">The type of the builder being used.</typeparam>
     public interface IIncludeBuilder<T, out TBuilder> : IDocumentIncludeBuilder<T, TBuilder>, ICounterIncludeBuilder<T, TBuilder>, ITimeSeriesIncludeBuilder<T, TBuilder>, ICompareExchangeValueIncludeBuilder<T, TBuilder>, IRevisionIncludeBuilder<T, TBuilder>
     {
     }

src/Raven.Client/Documents/Session/TimeSeries/TimeSeriesEntry.cs

@@ -18,6 +18,14 @@
 
 namespace Raven.Client.Documents.Session.TimeSeries
 {
+    /// <summary>
+    /// Represents an individual entry in a time series, storing a timestamp, associated values, and metadata.
+    /// </summary>
+    /// <remarks>
+    /// <see cref="TimeSeriesEntry"/> is used as a base type for time series data projections 
+    /// in operations such as <see cref="GetTimeSeriesOperation{TValues}"/>.
+    /// It contains a timestamp and associated values for a single entry within a time series.
+    /// </remarks>
     public class TimeSeriesEntry : ITimeSeriesQueryStreamEntry
     {
         public DateTime Timestamp { get; set; }