Correct documentation about ArrayHandles with Vec-like values

vtkm/cont/ArrayHandleGroupVecVariable.h

@@ -244,13 +244,15 @@ public:
 /// it contains three values of Vec-like objects with the data [0,1,2,3],
 /// [4,5], and [6,7,8].
 ///
-/// Note that this version of \c ArrayHandle breaks some of the assumptions
-/// about \c ArrayHandle a little bit. Typically, there is exactly one type for
-/// every value in the array, and this value is also the same between the
-/// control and execution environment. However, this class uses \c
-/// VecFromPortal it implement a Vec-like class that has a variable number of
-/// values, and this type can change between control and execution
-/// environments.
+/// Note that caution should be used with `ArrayHandleRuntimeVec` because the
+/// size of the `Vec` values is not known at compile time. Thus, the value
+/// type of this array is forced to a special `VecFromPortal` class that can cause
+/// surprises if treated as a `Vec`. In particular, the static `NUM_COMPONENTS`
+/// expression does not exist. Furthermore, new variables of type `VecFromPortal`
+/// cannot be created. This means that simple operators like `+` will not work
+/// because they require an intermediate object to be created. (Equal operators
+/// like `+=` do work because they are given an existing variable to place the
+/// output.)
 ///
 /// The offsets array is often derived from a list of sizes for each of the
 /// entries. You can use the convenience function \c

vtkm/cont/ArrayHandleRecombineVec.h

@@ -15,8 +15,6 @@
 #include <vtkm/cont/ArrayHandleStride.h>
 #include <vtkm/cont/DeviceAdapterTag.h>
 
-#include <vtkm/VecVariable.h>
-
 #include <vtkm/internal/ArrayPortalValueReference.h>
 
 namespace vtkm
@@ -586,9 +584,13 @@ public:
 ///
 /// Note that caution should be used with `ArrayHandleRecombineVec` because the
 /// size of the `Vec` values is not known at compile time. Thus, the value
-/// type of this array is forced to a `VecVariable`, which can cause surprises
-/// if treated as a `Vec`. In particular, the static `NUM_COMPONENTS` expression
-/// does not exist.
+/// type of this array is forced to a special `RecombineVec` class that can cause
+/// surprises if treated as a `Vec`. In particular, the static `NUM_COMPONENTS`
+/// expression does not exist. Furthermore, new variables of type `RecombineVec`
+/// cannot be created. This means that simple operators like `+` will not work
+/// because they require an intermediate object to be created. (Equal operators
+/// like `+=` do work because they are given an existing variable to place the
+/// output.)
 ///
 template <typename ComponentType>
 class ArrayHandleRecombineVec

vtkm/cont/ArrayHandleRuntimeVec.h

@@ -262,13 +262,15 @@ public:
 /// as a template parameter at compile time. `ArrayHandleRuntimeVec` can be used
 /// in this case.
 ///
-/// Note that this version of `ArrayHandle` breaks some of the assumptions
-/// about `ArrayHandle` a little bit. Typically, there is exactly one type for
-/// every value in the array, and this value is also the same between the
-/// control and execution environment. However, this class uses `VecFromPortal`
-/// it implement a `Vec`-like class that has a variable number of
-/// values, and this type can change between control and execution
-/// environments.
+/// Note that caution should be used with `ArrayHandleRuntimeVec` because the
+/// size of the `Vec` values is not known at compile time. Thus, the value
+/// type of this array is forced to a special `VecFromPortal` class that can cause
+/// surprises if treated as a `Vec`. In particular, the static `NUM_COMPONENTS`
+/// expression does not exist. Furthermore, new variables of type `VecFromPortal`
+/// cannot be created. This means that simple operators like `+` will not work
+/// because they require an intermediate object to be created. (Equal operators
+/// like `+=` do work because they are given an existing variable to place the
+/// output.)
 ///
 /// It is possible to provide an `ArrayHandleBasic` of the same component
 /// type as the underlying storage for this array. In this case, the array