Correct spelling and inherit documentation for BulkAll

russcam · russcam · commit e204fd304fb9 · 2018-10-18T12:57:41.000+10:00
diff --git a/src/Nest/Document/Multiple/BulkAll/BulkAllObservable.cs b/src/Nest/Document/Multiple/BulkAll/BulkAllObservable.cs
@@ -9,7 +9,7 @@ namespace Nest
 {
 	public class BulkAllObservable<T> : IDisposable, IObservable<IBulkAllResponse> where T : class
 	{
-		private readonly IBulkAllRequest<T> _partionedBulkRequest;
+		private readonly IBulkAllRequest<T> _partitionedBulkRequest;
 		private readonly IElasticClient _client;
 		private readonly TimeSpan _backOffTime;
 		private readonly int _backOffRetries;
@@ -21,22 +21,22 @@ public class BulkAllObservable<T> : IDisposable, IObservable<IBulkAllResponse> w
 		private readonly CancellationToken _compositeCancelToken;
 		private readonly CancellationTokenSource _compositeCancelTokenSource;
 		private readonly Func<IBulkResponseItem, T, bool> _retryPredicate;
-		private Action<IBulkResponseItem, T> _droppedDocumentCallBack;
+		private readonly Action<IBulkResponseItem, T> _droppedDocumentCallBack;
 
 		public BulkAllObservable(
 			IElasticClient client,
-			IBulkAllRequest<T> partionedBulkRequest,
+			IBulkAllRequest<T> partitionedBulkRequest,
 			CancellationToken cancellationToken = default(CancellationToken)
 		)
 		{
 			this._client = client;
-			this._partionedBulkRequest = partionedBulkRequest;
-			this._backOffRetries = this._partionedBulkRequest.BackOffRetries.GetValueOrDefault(CoordinatedRequestDefaults.BulkAllBackOffRetriesDefault);
-			this._backOffTime = (this._partionedBulkRequest?.BackOffTime?.ToTimeSpan() ?? CoordinatedRequestDefaults.BulkAllBackOffTimeDefault);
-			this._bulkSize = this._partionedBulkRequest.Size ?? CoordinatedRequestDefaults.BulkAllSizeDefault;
-			this._retryPredicate = this._partionedBulkRequest.RetryDocumentPredicate ?? RetryBulkActionPredicate;
-			this._droppedDocumentCallBack = this._partionedBulkRequest.DroppedDocumentCallback ?? DroppedDocumentCallbackDefault;
-			this._maxDegreeOfParallelism = _partionedBulkRequest.MaxDegreeOfParallelism ?? CoordinatedRequestDefaults.BulkAllMaxDegreeOfParallelismDefault;
+			this._partitionedBulkRequest = partitionedBulkRequest;
+			this._backOffRetries = this._partitionedBulkRequest.BackOffRetries.GetValueOrDefault(CoordinatedRequestDefaults.BulkAllBackOffRetriesDefault);
+			this._backOffTime = (this._partitionedBulkRequest?.BackOffTime?.ToTimeSpan() ?? CoordinatedRequestDefaults.BulkAllBackOffTimeDefault);
+			this._bulkSize = this._partitionedBulkRequest.Size ?? CoordinatedRequestDefaults.BulkAllSizeDefault;
+			this._retryPredicate = this._partitionedBulkRequest.RetryDocumentPredicate ?? RetryBulkActionPredicate;
+			this._droppedDocumentCallBack = this._partitionedBulkRequest.DroppedDocumentCallback ?? DroppedDocumentCallbackDefault;
+			this._maxDegreeOfParallelism = _partitionedBulkRequest.MaxDegreeOfParallelism ?? CoordinatedRequestDefaults.BulkAllMaxDegreeOfParallelismDefault;
 			this._compositeCancelTokenSource = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
 			this._compositeCancelToken = this._compositeCancelTokenSource.Token;
 		}
@@ -57,10 +57,10 @@ public IDisposable Subscribe(IObserver<IBulkAllResponse> observer)
 
 		private void BulkAll(IObserver<IBulkAllResponse> observer)
 		{
-			var documents = this._partionedBulkRequest.Documents;
-			var partioned = new PartitionHelper<T>(documents, this._bulkSize);
+			var documents = this._partitionedBulkRequest.Documents;
+			var partitioned = new PartitionHelper<T>(documents, this._bulkSize);
 #pragma warning disable 4014
-			partioned.ForEachAsync(
+			partitioned.ForEachAsync(
 #pragma warning restore 4014
 				(buffer, page) => this.BulkAsync(buffer, page, 0),
 				(buffer, response) => observer.OnNext(response),
@@ -89,8 +89,8 @@ private void OnCompleted(Exception exception, IObserver<IBulkAllResponse> observ
 
 		private void RefreshOnCompleted()
 		{
-			if (!this._partionedBulkRequest.RefreshOnCompleted ) return;
-			var indices = this._partionedBulkRequest.RefreshIndices ?? this._partionedBulkRequest.Index;
+			if (!this._partitionedBulkRequest.RefreshOnCompleted) return;
+			var indices = this._partitionedBulkRequest.RefreshIndices ?? this._partitionedBulkRequest.Index;
 			if (indices == null) return;
 			var refresh = this._client.Refresh(indices);
 			if (!refresh.IsValid) throw Throw($"Refreshing after all documents have indexed failed", refresh.ApiCall);
@@ -100,7 +100,7 @@ private async Task<IBulkAllResponse> BulkAsync(IList<T> buffer, long page, int b
 		{
 			this._compositeCancelToken.ThrowIfCancellationRequested();
 
-			var r = this._partionedBulkRequest;
+			var r = this._partitionedBulkRequest;
 			var response = await this._client.BulkAsync(s =>
 				{
 					s.Index(r.Index).Type(r.Type);
@@ -134,7 +134,7 @@ private async Task<IBulkAllResponse> BulkAsync(IList<T> buffer, long page, int b
 			else if (retryDocuments.Count > 0)
 				throw this.ThrowOnBadBulk(response, $"Bulk indexing failed and after retrying {backOffRetries} times");
 
-			this._partionedBulkRequest.BackPressure?.Release();
+			this._partitionedBulkRequest.BackPressure?.Release();
 			return new BulkAllResponse { Retries = backOffRetries, Page = page };
 		}
 
@@ -145,7 +145,7 @@ private void HandleDroppedDocuments(List<Tuple<IBulkResponseItem, T>> documentsW
 				.ToList();
 			if (droppedDocuments.Count <= 0) return;
 			foreach (var dropped in droppedDocuments) this._droppedDocumentCallBack(dropped.Item1, dropped.Item2);
-			if (!this._partionedBulkRequest.ContinueAfterDroppedDocuments)
+			if (!this._partitionedBulkRequest.ContinueAfterDroppedDocuments)
 				throw this.ThrowOnBadBulk(response, $"BulkAll halted after receiving failures that can not be retried from _bulk");
 		}
 
@@ -183,7 +183,7 @@ private async Task<IBulkAllResponse> RetryDocuments(long page, int backOffRetrie
 		private Exception ThrowOnBadBulk(IElasticsearchResponse response, string message)
 		{
 			this._incrementFailed();
-			this._partionedBulkRequest.BackPressure?.Release();
+			this._partitionedBulkRequest.BackPressure?.Release();
 			return Throw(message, response.ApiCall);
 		}
 		private static ElasticsearchClientException Throw(string message, IApiCallDetails details) =>
diff --git a/src/Nest/Document/Multiple/BulkAll/BulkAllRequest.cs b/src/Nest/Document/Multiple/BulkAll/BulkAllRequest.cs
@@ -1,26 +1,26 @@
 ﻿using System;
 using System.Collections.Generic;
+using System.Linq;
 using System.Threading;
 using Elasticsearch.Net;
 
 namespace Nest
 {
 	public interface IBulkAllRequest<T> where T : class
 	{
-		/// <summary> In case of a 429 (too busy) how long should we wait before retrying</summary>
+		/// <summary> In case of a HTTP 429 (Too Many Requests) response status code, how long should we wait before retrying</summary>
 		Time BackOffTime { get; set; }
 
-		/// <summary> In case of a 429 (too busy) how many times should we automatically back off before failing</summary>
+		/// <summary> In case of a HTTP 429 (Too Many Requests) response status code, how many times should we automatically back off before failing</summary>
 		int? BackOffRetries { get; set; }
 
 		/// <summary> The number of documents to send per bulk</summary>
 		int? Size { get; set; }
 
 		///<summary>
-		/// The documents to send to elasticsearch, try to keep the IEnumerable lazy.
-		/// The bulk observable will ToList() each partitioned page in a lazy fashion, to keep memory consumption to a minimum.
-		/// It makes no sense to set this to an list of 1 million records because all of those million records need to be in memory
-		/// Make use of c#'s lazy generator!
+		/// The documents to send to Elasticsearch, ideally lazily evaluated by using <see langword="yield"/>
+		/// return to provide each document.
+		/// <see cref="BulkAllObservable{T}"/> will eager evaluate each partitioned page when operating on it, using <see cref="Enumerable.ToList{T}"/>.
 		///</summary>
 		IEnumerable<T> Documents { get; }
 
@@ -35,12 +35,12 @@ public interface IBulkAllRequest<T> where T : class
 
 		///<summary>
 		///Sets the number of shard copies that must be active before proceeding with the bulk operation.
-		///Defaults to 1, meaning the primary shard only. Set to `all` for all shard copies, otherwise set to any
+		///Defaults to <c>1</c>, meaning the primary shard only. Set to `all` for all shard copies, otherwise set to any
 		///non-negative value less than or equal to the total number of copies for the shard (number of replicas + 1)
 		///</summary>
 		int? WaitForActiveShards { get; set; }
 
-		///<summary>Refresh the index after performing each operation (elasticsearch will refresh locally)</summary>
+		///<summary>Refresh the index after performing each operation (Elasticsearch will refresh locally)</summary>
 		[Obsolete("This option is scheduled for deletion in 7.0, refreshing on each _bulk makes little sense for BulkAll")]
 		Refresh? Refresh { get; set; }
 
@@ -62,8 +62,8 @@ public interface IBulkAllRequest<T> where T : class
 		string Pipeline { get; set; }
 
 		/// <summary>
-		/// By default the bulkall helper simply calls BulkDescriptor.IndexMany on the buffer.
-		/// There might be case where you'd like more control over this. By setting this callback you are in complete control
+		/// By default, <see cref="BulkAllObservable{T}"/> calls <see cref="BulkDescriptor.IndexMany{T}"/> on the buffer.
+		/// There might be case where you'd like more control over the bulk operation. By setting this callback, you are in complete control
 		/// of describing how the buffer should be translated to a bulk operation.
 		/// </summary>
 		Action<BulkDescriptor, IList<T>> BufferToBulk { get; set; }
@@ -76,7 +76,8 @@ public interface IBulkAllRequest<T> where T : class
 		ProducerConsumerBackPressure BackPressure { get; set; }
 
 		/// <summary>
-		/// A predicate which controls which documents should be retried, defaults to failed bulk items with status code 429
+		/// A predicate to control which documents should be retried.
+		/// Defaults to failed bulk items with a HTTP 429 (Too Many Requests) response status code.
 		/// </summary>
 		Func<IBulkResponseItem, T, bool> RetryDocumentPredicate { get; set; }
 
@@ -88,8 +89,8 @@ public interface IBulkAllRequest<T> where T : class
 
 		/// <summary>
 		/// If a bulk operation fails because it receives documents it can not retry they will be fed to this callback.
-		/// If <see cref="ContinueAfterDroppedDocuments"/> is set to true processing will continue, so this callback can be used
-		/// to feed into a dead letter queue. Otherwise the bulk all indexation will be halted.
+		/// If <see cref="ContinueAfterDroppedDocuments"/> is set to <c>true</c> processing will continue, so this callback can be used
+		/// to feed into a dead letter queue. Otherwise bulk all indexing will be halted.
 		/// </summary>
 		Action<IBulkResponseItem, T> DroppedDocumentCallback { get; set; }
 
@@ -177,54 +178,56 @@ public BulkAllDescriptor(IEnumerable<T> documents)
 			((IBulkAllRequest<T>)this).Type = typeof(T);
 		}
 
-		/// <inheritdoc />
-		public BulkAllDescriptor<T> MaxDegreeOfParallelism(int? parallism) =>
-			Assign(a => a.MaxDegreeOfParallelism = parallism);
+		/// <inheritdoc cref="IBulkAllRequest{T}.MaxDegreeOfParallelism" />
+		public BulkAllDescriptor<T> MaxDegreeOfParallelism(int? parallelism) =>
+			Assign(a => a.MaxDegreeOfParallelism = parallelism);
 
-		/// <inheritdoc />
+		/// <inheritdoc cref="IBulkAllRequest{T}.Size" />
 		public BulkAllDescriptor<T> Size(int? size) => Assign(a => a.Size = size);
 
-		/// <inheritdoc />
+		/// <inheritdoc cref="IBulkAllRequest{T}.BackOffRetries" />
 		public BulkAllDescriptor<T> BackOffRetries(int? backoffs) =>
 			Assign(a => a.BackOffRetries = backoffs);
 
-		/// <inheritdoc />
+		/// <inheritdoc cref="IBulkAllRequest{T}.BackOffTime" />
 		public BulkAllDescriptor<T> BackOffTime(Time time) => Assign(a => a.BackOffTime = time);
 
-		/// <inheritdoc />
+		/// <inheritdoc cref="IBulkAllRequest{T}.Index" />
 		public BulkAllDescriptor<T> Index(IndexName index) => Assign(a => a.Index = index);
 
-		/// <inheritdoc />
+		/// <inheritdoc cref="IBulkAllRequest{T}.Index" />
 		public BulkAllDescriptor<T> Index<TOther>() where TOther : class => Assign(a => a.Index = typeof(TOther));
 
-		/// <inheritdoc />
+		/// <inheritdoc cref="IBulkAllRequest{T}.Type" />
 		public BulkAllDescriptor<T> Type(TypeName type) => Assign(a => a.Type = type);
 
-		/// <inheritdoc />
+		/// <inheritdoc cref="IBulkAllRequest{T}.Type" />
 		public BulkAllDescriptor<T> Type<TOther>() where TOther : class => Assign(a => a.Type = typeof(TOther));
 
-		/// <inheritdoc />
+		/// <inheritdoc cref="IBulkAllRequest{T}.RefreshOnCompleted" />
 		public BulkAllDescriptor<T> RefreshOnCompleted(bool refresh = true) => Assign(p => p.RefreshOnCompleted = refresh);
 
-		/// <inheritdoc />
+		/// <inheritdoc cref="IBulkAllRequest{T}.Refresh" />
+#pragma warning disable 618
 		public BulkAllDescriptor<T> Refresh(Refresh? refresh) => Assign(p => p.Refresh = refresh);
+#pragma warning restore 618
 
 		/// <inheritdoc cref="IBulkAllRequest{T}.RefreshIndices"/>
 		public BulkAllDescriptor<T> RefreshIndices(Indices indicesToRefresh) => Assign(a => a.RefreshIndices = indicesToRefresh);
 
-		/// <inheritdoc />
+		/// <inheritdoc cref="IBulkAllRequest{T}.Routing"/>
 		public BulkAllDescriptor<T> Routing(Routing routing) => Assign(p => p.Routing = routing);
 
-		/// <inheritdoc />
+		/// <inheritdoc cref="IBulkAllRequest{T}.Timeout"/>
 		public BulkAllDescriptor<T> Timeout(Time timeout) => Assign(p => p.Timeout = timeout);
 
-		/// <inheritdoc />
+		/// <inheritdoc cref="IBulkAllRequest{T}.Pipeline"/>
 		public BulkAllDescriptor<T> Pipeline(string pipeline) => Assign(p => p.Pipeline = pipeline);
 
-		/// <inheritdoc />
+		/// <inheritdoc cref="IBulkAllRequest{T}.BufferToBulk"/>
 		public BulkAllDescriptor<T> BufferToBulk(Action<BulkDescriptor, IList<T>> modifier) => Assign(p => p.BufferToBulk = modifier);
 
-		/// <inheritdoc />
+		/// <inheritdoc cref="IBulkAllRequest{T}.RetryDocumentPredicate"/>
 		public BulkAllDescriptor<T> RetryDocumentPredicate(Func<IBulkResponseItem, T, bool> predicate) =>
 			Assign(p => p.RetryDocumentPredicate = predicate);
 
@@ -243,11 +246,7 @@ public BulkAllDescriptor<T> BackPressure(int maxConcurrency, int? backPressureFa
 		/// <inheritdoc cref="IBulkAllRequest{T}.ContinueAfterDroppedDocuments" />
 		public BulkAllDescriptor<T> ContinueAfterDroppedDocuments(bool proceed = true) => Assign(p => p.ContinueAfterDroppedDocuments = proceed);
 
-		/// <summary>
-		/// If <see cref="ContinueAfterDroppedDocuments"/> is set to false (not the default) dropped messages will be fed through
-		/// this callback. Use this if you don't expect many failures and want to feed these dropped messages in a dead letter queue
-		/// for instance.
-		/// </summary>
+		/// <inheritdoc cref="IBulkAllRequest{T}.DroppedDocumentCallback"/>
 		public BulkAllDescriptor<T> DroppedDocumentCallback(Action<IBulkResponseItem, T> callback) =>
 			Assign(p => p.DroppedDocumentCallback = callback);
 
