Fix many warnings from doxygen

There are still some warnings left:

* Some text in markdown files are incorrectly picked up as
  doxygen commands
* ArrayPortalTransform weirdly inherits from a specialized
  version of itself. It's technically correct C++ code, but
  gives doxygen fits.

CMake/doxyfile.in

@@ -145,7 +145,7 @@ INPUT                  += @VTKm_SOURCE_DIR@/vtkm
 
 USE_MDFILE_AS_MAINPAGE = README.md
 
-FILE_PATTERNS          = *.cxx *.h *.cu
+FILE_PATTERNS          = *.h
 
 RECURSIVE              = YES
 
@@ -303,9 +303,9 @@ GENERATE_XML           = NO
 
 XML_OUTPUT             = xml
 
-XML_SCHEMA             =
+#XML_SCHEMA             =
 
-XML_DTD                =
+#XML_DTD                =
 
 XML_PROGRAMLISTING     = YES
 
@@ -344,6 +344,7 @@ INCLUDE_PATH           = @VTKm_SOURCE_DIR@ @VTKm_BINARY_DIR@
 INCLUDE_FILE_PATTERNS  =
 
 PREDEFINED             = DOXYGEN
+PREDEFINED             += VTKM_DOXYGEN_ONLY
 
 EXPAND_AS_DEFINED      =
 

vtkm/VecAxisAlignedPointCoordinates.h

@@ -67,7 +67,7 @@ const vtkm::FloatDefault VecAxisAlignedPointCoordinatesOffsetTable[8][3] = {
 /// \brief An implicit vector for point coordinates in axis aligned cells. For
 /// internal use only.
 ///
-/// The \C VecAxisAlignedPointCoordinates class is a Vec-like class that holds
+/// The \c VecAxisAlignedPointCoordinates class is a Vec-like class that holds
 /// the point coordinates for a axis aligned cell. The class is templated on the
 /// dimensions of the cell, which can be 1 (for a line).
 ///

vtkm/cont/CellSetExplicit.h

@@ -266,6 +266,8 @@ struct CellSetExplicitConnectivityChooser<CellSetType,
 
 } // namespace detail
 
+/// \cond
+/// Make doxygen ignore this section
 #ifndef vtk_m_cont_CellSetExplicit_cxx
 extern template class VTKM_CONT_TEMPLATE_EXPORT CellSetExplicit<>; // default
 extern template class VTKM_CONT_TEMPLATE_EXPORT CellSetExplicit<
@@ -274,6 +276,7 @@ extern template class VTKM_CONT_TEMPLATE_EXPORT CellSetExplicit<
   VTKM_DEFAULT_CONNECTIVITY_STORAGE_TAG,
   typename vtkm::cont::ArrayHandleCounting<vtkm::Id>::StorageTag>; // CellSetSingleType base
 #endif
+/// \endcond
 }
 } // namespace vtkm::cont
 

vtkm/cont/StorageBasic.h

@@ -301,6 +301,8 @@ namespace cont
 namespace internal
 {
 
+/// \cond
+/// Make doxygen ignore this section
 extern template class VTKM_CONT_TEMPLATE_EXPORT Storage<char, StorageTagBasic>;
 extern template class VTKM_CONT_TEMPLATE_EXPORT Storage<vtkm::Int8, StorageTagBasic>;
 extern template class VTKM_CONT_TEMPLATE_EXPORT Storage<vtkm::UInt8, StorageTagBasic>;
@@ -334,6 +336,7 @@ extern template class VTKM_CONT_TEMPLATE_EXPORT
   Storage<vtkm::Vec<vtkm::Float32, 4>, StorageTagBasic>;
 extern template class VTKM_CONT_TEMPLATE_EXPORT
   Storage<vtkm::Vec<vtkm::Float64, 4>, StorageTagBasic>;
+/// \endcond
 }
 }
 }

vtkm/cont/VirtualObjectCache.h

@@ -41,24 +41,24 @@ namespace cont
 ///
 /// The template parameter \c VirtualObject is the class that acts as the
 /// interface. Following is a method for implementing such classes:
-/// 1. Create a <tt>const void*<\tt> member variable that will hold a
+/// 1. Create a <tt>const void*</tt> member variable that will hold a
 ///    reference to the target class.
 /// 2. For each virtual-like method:
 ///    a. Create a typedef for a function with the same signature,
-///       except for an extra <tt>const void*<\tt> argument.
+///       except for an extra <tt>const void*</tt> argument.
 ///    b. Create a function pointer member variable with the type of the
 ///       associated typedef from 2a.
 ///    c. Create an implementation of the method, that calls the associated
 ///       function pointer with the void pointer to the target class as one of
 ///       the arguments.
 /// 3. Create the following template function:
-///    <tt>
+///    \code{.cpp}
 ///       template<typename TargetClass>
 ///       VTKM_EXEC void Bind(const TargetClass *deviceTarget);
-///    </tt>
+///    \endcode
 ///    This function should set the void pointer from 1 to \c deviceTarget,
 ///    and assign the function pointers from 2b to functions that cast their
-///    first argument to <tt>const TargetClass*<\tt> and call the corresponding
+///    first argument to <tt>const TargetClass*</tt> and call the corresponding
 ///    member function on it.
 ///
 /// Both \c VirtualObject and target class objects should be bitwise copyable.

vtkm/exec/arg/ThreadIndicesPointNeighborhood.h

@@ -198,17 +198,22 @@ struct BoundaryState
 
 namespace detail
 {
-// Helper function to increase an index to 3D.
+/// Given a \c Vec of (semi) aribtrary size, inflate it to a vtkm::Id3 by padding with zeros.
+///
 inline VTKM_EXEC vtkm::Id3 To3D(vtkm::Id3 index)
 {
   return index;
 }
 
+/// Given a \c Vec of (semi) aribtrary size, inflate it to a vtkm::Id3 by padding with zeros.
+/// \overload
 inline VTKM_EXEC vtkm::Id3 To3D(vtkm::Id2 index)
 {
   return vtkm::Id3(index[0], index[1], 1);
 }
 
+/// Given a \c Vec of (semi) aribtrary size, inflate it to a vtkm::Id3 by padding with zeros.
+/// \overload
 inline VTKM_EXEC vtkm::Id3 To3D(vtkm::Vec<vtkm::Id, 1> index)
 {
   return vtkm::Id3(index[0], 1, 1);

vtkm/exec/arg/ThreadIndicesTopologyMap.h

@@ -158,32 +158,43 @@ private:
 namespace detail
 {
 
-// Helper function to increase an index to 3D.
+/// Given a \c Vec of (semi) aribtrary size, inflate it to a vtkm::Id3 by padding with zeros.
+///
 static inline VTKM_EXEC vtkm::Id3 InflateTo3D(vtkm::Id3 index)
 {
   return index;
 }
 
+/// Given a \c Vec of (semi) aribtrary size, inflate it to a vtkm::Id3 by padding with zeros.
+/// \overload
 static inline VTKM_EXEC vtkm::Id3 InflateTo3D(vtkm::Id2 index)
 {
   return vtkm::Id3(index[0], index[1], 0);
 }
 
+/// Given a \c Vec of (semi) aribtrary size, inflate it to a vtkm::Id3 by padding with zeros.
+/// \overload
 static inline VTKM_EXEC vtkm::Id3 InflateTo3D(vtkm::Vec<vtkm::Id, 1> index)
 {
   return vtkm::Id3(index[0], 0, 0);
 }
 
+/// Given a \c Vec of (semi) aribtrary size, inflate it to a vtkm::Id3 by padding with zeros.
+/// \overload
 static inline VTKM_EXEC vtkm::Id3 InflateTo3D(vtkm::Id index)
 {
   return vtkm::Id3(index, 0, 0);
 }
 
+/// Given a vtkm::Id3, reduce down to an identifer of choice.
+///
 static inline VTKM_EXEC vtkm::Id3 Deflate(const vtkm::Id3& index, vtkm::Id3)
 {
   return index;
 }
 
+/// Given a vtkm::Id3, reduce down to an identifer of choice.
+/// \overload
 static inline VTKM_EXEC vtkm::Id2 Deflate(const vtkm::Id3& index, vtkm::Id2)
 {
   return vtkm::Id2(index[0], index[1]);

vtkm/internal/FunctionInterface.h

@@ -96,7 +96,7 @@ class FunctionInterfaceDynamicTransformContContinue;
 /// \brief Holds parameters and result of a function.
 ///
 /// To make VTK-m easier for the end user developer, the
-/// vtkm::cont::Dispatcher*::Invoke() method takes an arbitrary amount of
+/// \c Invoke method of dispatchers takes an arbitrary amount of
 /// arguments that get transformed and swizzled into arguments and return value
 /// for a worklet operator. In between these two invocations a complicated
 /// series of transformations and operations can occur.

vtkm/worklet/spatialstructure/KdTree3DConstruction.h

@@ -562,7 +562,7 @@ public:
     }
   }
 
-  /// \breif Construct KdTree from x y z coordinate vector.
+  /// \brief Construct KdTree from x y z coordinate vector.
   ///
   /// This method constructs an array based KD-Tree from x, y, z coordinates of points in \c
   /// coordi_Handle. The method rotates between x, y and z axis and splits input points into
@@ -573,6 +573,7 @@ public:
   /// \param coordi_Handle (in) x, y, z coordinates of input points
   /// \param pointId_Handle (out) returns indices to leaf nodes of the KD-tree
   /// \param splitId_Handle (out) returns indices to internal nodes of the KD-tree
+  /// \param device the device to run the construction on
   // Leaf Node vector and internal node (split) vectpr
   template <typename CoordType, typename CoordStorageTag, typename DeviceAdapter>
   void Run(const vtkm::cont::ArrayHandle<vtkm::Vec<CoordType, 3>, CoordStorageTag>& coordi_Handle,

vtkm/worklet/spatialstructure/KdTree3DNNSearch.h

@@ -194,7 +194,7 @@ public:
   /// Given x, y, z coordinate of of training data points in \c coordi_Handle, indices to KD-tree
   /// leaf nodes in \c pointId_Handle and indices to internal nodes in \c splitId_Handle, search
   /// for nearest neighbors in the training data points for each of testing points in \c qc_Handle.
-  /// Returns indices to nearest neighbor in \cnnId_Handle and distance to nearest neighbor in
+  /// Returns indices to nearest neighbor in \c nnId_Handle and distance to nearest neighbor in
   /// \c nnDis_Handle.
 
   template <typename CoordType,