review(CompositeArr): improve doc + remove md + add final

Common/ImplicitArrays/vtkCompositeImplicitBackend.h

@@ -23,7 +23,8 @@
  * This structure can be classified as a closure and can be called using syntax similar to a
  * function call.
  *
- * The class implements a flat binary tree like structure for facilitating fast access.
+ * This class uses indirect addressing of cached arrays to provide an access compute complexity of
+ * O(log_2(number_of_arrays)) through its `()` operator.
  *
  * At construction it takes an array arrays in order to represent their concatenation.
  *
@@ -56,7 +57,7 @@
 VTK_ABI_NAMESPACE_BEGIN
 class vtkDataArray;
 template <typename ValueType>
-class vtkCompositeImplicitBackend
+class vtkCompositeImplicitBackend final
 {
 public:
   /**
@@ -69,7 +70,10 @@ public:
 
   /**
    * Indexing operator for the composite of the two arrays respecting the `vtkImplicitArray`
-   * expectations
+   * expectations.
+   *
+   * Conceptually, the composite array uses a binary search algorithm through the use of
+   * `std::upper_bounds` to offer a compute complexity of O(log_2(n_arrays))
    */
   ValueType operator()(int idx) const;
 

Common/ImplicitArrays/vtkCompositeImplicitBackend.txx

@@ -19,11 +19,16 @@
 #include "vtkArrayDispatchImplicitArrayList.h"
 #include "vtkDataArray.h"
 #include "vtkDataArrayRange.h"
+#include "vtkImplicitArray.h"
 #include "vtkSmartPointer.h"
 
 namespace
 {
 //-----------------------------------------------------------------------
+/*
+ * A generic interface towards a typed get value. Specialized structures should inherit from this
+ * struct in order to abstractify the array type from the GetValue usage.
+ */
 template <typename ValueType>
 struct TypedArrayCache
 {
@@ -31,6 +36,10 @@ struct TypedArrayCache
   virtual ~TypedArrayCache() = default;
 };
 
+/*
+ * A templated implementation of the TypedArrayCache above that should be used for arrays that
+ * implement the `GetValue` method from the `vtkGenericDataArray` interface.
+ */
 template <typename ValueType, typename ArrayT>
 struct SpecializedCache : public TypedArrayCache<ValueType>
 {
@@ -49,6 +58,10 @@ private:
   vtkSmartPointer<ArrayT> Array;
 };
 
+/*
+ * An implementation of TypedArrayCache for `vtkDataArray` that acts as a fallback implementation
+ * for arrays whose base type cannot be determined by `vtkArrayDispatch`.
+ */
 template <typename ValueType>
 struct SpecializedCache<ValueType, vtkDataArray> : public TypedArrayCache<ValueType>
 {
@@ -70,6 +83,10 @@ private:
 };
 
 //-----------------------------------------------------------------------
+/*
+ * A worker structure to be used with `vtkArrayDispatch` in order to cache typed versions of arrays
+ * once for improving random access speed.
+ */
 template <typename ValueType>
 struct CacheDispatchWorker
 {
@@ -82,6 +99,11 @@ struct CacheDispatchWorker
 
 //-----------------------------------------------------------------------
 template <typename ArrayList, typename ValueType>
+/*
+ * A structure that wraps around a TypedArrayCache and can serve as a backend to a
+ * `vtkImplicitArray`. Its constructor is what uses dispatches the underlying array into a typed
+ * cache.
+ */
 struct TypedCacheWrapper
 {
   TypedCacheWrapper(vtkDataArray* arr)
@@ -110,6 +132,11 @@ struct vtkCompositeImplicitBackend<ValueType>::Internals
   using CachedBackend = ::TypedCacheWrapper<InternalArrayList, ValueType>;
   using CachedArray = vtkImplicitArray<CachedBackend>;
 
+  /*
+   * Construct an internal structure from any range of iterators providing a stream of
+   * `vtkDataArray*`s. At construction, every array is dispatched into a cache and the offsets are
+   * calculated to enable fast binary search in `vtkCompositeImplicitBackend::operator()`.
+   */
   template <class Iterator>
   Internals(Iterator first, Iterator last)
   {

Documentation/release/dev/improve-vtkCompositeArray.md

@@ -1,5 +0,0 @@
-## Improve performance of `vtkCompositeArray`
-
-Flattening out the internal tree structure of the `vtkCompositeImplicitBackend` has increased access performance considerably when dealing with multi-level binary trees by avoiding intermediate calls through the `vtkImplicitArray`structure.
-
-This has led to a significant API change in the `vtkCompositeImplicitBackend` constructor which now takes a `std::vector<vtkDataArray*>` instead of two `vtkDataArray*`s directly leading to better quality of life for users as well.