Improve the overall doxygen content for vtk-m.

CMake/doxyfile.in

@@ -193,7 +193,7 @@ VERBATIM_HEADERS       = YES
 
 ALPHABETICAL_INDEX     = YES
 
-COLS_IN_ALPHA_INDEX    = 5
+COLS_IN_ALPHA_INDEX    = 2
 
 IGNORE_PREFIX          =
 
@@ -229,7 +229,7 @@ DISABLE_INDEX          = NO
 
 ENUM_VALUES_PER_LINE   = 4
 
-GENERATE_TREEVIEW      = YES
+GENERATE_TREEVIEW      = NO
 
 TREEVIEW_WIDTH         = 250
 

vtkm/Types.h

@@ -31,54 +31,111 @@
 
 /*!
  * \namespace vtkm
- * \brief VTKm Toolkit.
+ * \brief VTK-m Toolkit.
  *
- * vtkm is the namespace for the VTKm Toolkit. It contains other sub namespaces,
- * as well as basic data types and functions callable from all components in VTKm
+ * vtkm is the namespace for the VTK-m Toolkit. It contains other sub namespaces,
+ * as well as basic data types and functions callable from all components in VTK-m
  * toolkit.
  *
  * \namespace vtkm::cont
- * \brief VTKm Control Environment.
+ * \brief VTK-m Control Environment.
  *
- * vtkm::cont defines the publicly accessible API for the VTKm Control
- * Environment. Users of the VTKm Toolkit can use this namespace to access the
+ * vtkm::cont defines the publicly accessible API for the VTK-m Control
+ * Environment. Users of the VTK-m Toolkit can use this namespace to access the
  * Control Environment.
  *
+ * \namespace vtkm::cont::arg
+ * \brief Transportation controls for Control Environment Objects.
+ *
+ * vtkm::cont::arg includes the classes that allows the vtkm::worklet::Dispatchers
+ * to request Control Environment Objects to be transfered to the Execution Environment.
+ *
  * \namespace vtkm::cont::cuda
  * \brief CUDA implementation for Control Environment.
  *
- * vtkm::cont::cuda includes the code to implement the VTKm Control Environment
- * for CUDA-based platforms.
+ * vtkm::cont::cuda includes the code to implement the VTK-m Control Environment
+ * for the CUDA-based device adapter.
+ *
+ * \namespace vtkm::cont::serial
+ * \brief Serial implementation for Control Environment.
+ *
+ * vtkm::cont::serial includes the code to implement the VTK-m Control Environment
+ * for the serial device adapter.
+ *
+ * \namespace vtkm::cont::tbb
+ * \brief TBB implementation for Control Environment.
+ *
+ * vtkm::cont::tbb includes the code to implement the VTK-m Control Environment
+ * for the TBB-based device adapter.
  *
  * \namespace vtkm::exec
- * \brief VTKm Execution Environment.
+ * \brief VTK-m Execution Environment.
  *
- * vtkm::exec defines the publicly accessible API for the VTKm Execution
+ * vtkm::exec defines the publicly accessible API for the VTK-m Execution
  * Environment. Worklets typically use classes/apis defined within this
  * namespace alone.
  *
  * \namespace vtkm::exec::cuda
  * \brief CUDA implementation for Execution Environment.
  *
- * vtkm::exec::cuda includes the code to implement the VTKm Execution Environment
- * for CUDA-based platforms.
+ * vtkm::exec::cuda includes the code to implement the VTK-m Execution Environment
+ * for the CUDA-based device adapter.
+ *
+ * \namespace vtkm::exec::serial
+ * \brief CUDA implementation for Execution Environment.
+ *
+ * vtkm::exec::serial includes the code to implement the VTK-m Execution Environment
+ * for the serial device adapter.
+ *
+ * \namespace vtkm::exec::tbb
+ * \brief TBB implementation for Execution Environment.
+ *
+ * vtkm::exec::tbb includes the code to implement the VTK-m Execution Environment
+ * for the TBB device adapter.
+ *
+ * \namespace vtkm::filter
+ * \brief VTK-m Filters
+ *
+ * vtkm::filter is the collection of predefined filters that take data as input
+ * and write new data as output. Filters operate on vtkm::cont::DataSet objects,
+ * vtkm::cont::Fields, and other runtime typeless objects.
  *
  * \namespace vtkm::internal
- * \brief VTKm Internal Environment
+ * \brief VTK-m Internal Environment
  *
  * vtkm::internal defines API which is internal and subject to frequent
- * change. This should not be used for projects using VTKm. Instead it servers
- * are a reference for the developers of VTKm.
+ * change. This should not be used for projects using VTK-m. Instead it servers
+ * are a reference for the developers of VTK-m.
  *
  * \namespace vtkm::interop
- * \brief Utility opengl interop functions
+ * \brief VTK-m OpenGL Interoperability
  *
  * vtkm::interop defines the publicly accessible API for interoperability between
- * vtkm and opengl.
+ * vtkm and OpenGL.
+ *
+ * \namespace vtkm::io
+ * \brief VTK-m IO
+ *
+ * vtkm::io defines API for basic reading of VTK files. Intended to be used for
+ * examples and testing.
+ *
+ * \namespace vtkm::rendering
+ * \brief VTK-m Rendering
+ *
+ * vtkm::rendering defines API for
  *
  * \namespace vtkm::testing
  * \brief Internal testing classes
  *
+ * \namespace vtkm::worklet
+ * \brief VTK-m Worklets
+ *
+ * vtkm::worklet defines API for the low level worklets that operate on an element of data,
+ * and the dispatcher that execute them in the execution environment.
+ *
+ * VTK-m provides numerous worklet implementations. These worklet implementations for the most
+ * part provide the underlying implementations of the algorithms in vtkm::filter.
+ *
  */
 
 namespace vtkm
@@ -87,9 +144,6 @@ namespace vtkm
 // Typedefs for basic types.
 //*****************************************************************************
 
-/// Alignment requirements are prescribed by CUDA on device (Table B-1 in NVIDIA
-/// CUDA C Programming Guide 4.0)
-
 #if VTKM_SIZE_FLOAT == 4
 typedef float Float32;
 #else

vtkm/cont/DeviceAdapterAlgorithm.h

@@ -28,7 +28,7 @@
 #ifdef _WIN32
 #include <sys/timeb.h>
 #include <sys/types.h>
-#else //!_WIN32
+#else // _WIN32
 #include <limits.h>
 #include <sys/time.h>
 #include <unistd.h>

vtkm/cont/tbb/internal/parallel_sort.h

@@ -216,6 +216,7 @@ void parallel_quick_sort(RandomAccessIterator begin, RandomAccessIterator end, c
 } // namespace internal
 //! @endcond
 
+//! @cond INTERNAL
 /** \page parallel_sort_iter_req Requirements on iterators for parallel_sort
     Requirements on value type \c T of \c RandomAccessIterator for \c parallel_sort:
     - \code void swap( T& x, T& y ) \endcode        Swaps \c x and \c y
@@ -231,6 +232,7 @@ void parallel_quick_sort(RandomAccessIterator begin, RandomAccessIterator end, c
 /** The compare function object is used for all comparisons between elements during sorting.
     The compare object must define a bool operator() function.
     @ingroup algorithms **/
+//! @endcond
 template <typename RandomAccessIterator, typename Compare>
 void parallel_sort(RandomAccessIterator begin, RandomAccessIterator end, const Compare& comp)
 {

vtkm/filter/CellAverage.h

@@ -28,7 +28,13 @@ namespace vtkm
 {
 namespace filter
 {
-
+/// \brief  Point to cell interpolation filter.
+///
+/// CellAverage is a filter that transforms point data (i.e., data
+/// specified at cell points) into cell data (i.e., data specified per cell).
+/// The method of transformation is based on averaging the data
+/// values of all points used by particular cell.
+///
 class CellAverage : public vtkm::filter::FilterCell<CellAverage>
 {
 public:

vtkm/filter/ClipWithField.h

@@ -28,7 +28,12 @@ namespace vtkm
 {
 namespace filter
 {
-
+/// \brief Clip a dataset using a field
+///
+/// Clip a dataset using a given field value. All points that are less than that
+/// value are considered outside, and will be discarded. All points that are greater
+/// are kept.
+/// The resulting geometry will not be water tight.
 class ClipWithField : public vtkm::filter::FilterDataSetWithField<ClipWithField>
 {
 public:

vtkm/filter/ClipWithImplicitFunction.h

@@ -32,6 +32,11 @@ namespace vtkm
 namespace filter
 {
 
+/// \brief Clip a dataset using an implicit function
+///
+/// Clip a dataset using a given implicit function value, such as vtkm::cont::Sphere
+/// or vtkm::cont::Frustum.
+/// The resulting geometry will not be water tight.
 class ClipWithImplicitFunction : public vtkm::filter::FilterDataSet<ClipWithImplicitFunction>
 {
 public:

vtkm/filter/ContourTreeUniform.h

@@ -74,13 +74,19 @@ namespace vtkm
 namespace filter
 {
 
+/// \brief Construct the ContourTree for a 2D Mesh
+///
+/// Output field "saddlePeak" which is pairs of vertex ids indicating saddle and
+/// peak of contour
+/// Based on the algorithm presented in the paper:
+//  “Parallel Peak Pruning for Scalable SMP Contour Tree Computation.”
 class ContourTreeMesh2D : public vtkm::filter::FilterField<ContourTreeMesh2D>
 {
 public:
   VTKM_CONT
   ContourTreeMesh2D();
 
-  // Output field "saddlePeak" which is pairs of vertex ids indicating saddle and peak of contour
+  /// Output field
   template <typename T, typename StorageType, typename DerivedPolicy, typename DeviceAdapter>
   VTKM_CONT vtkm::filter::ResultField DoExecute(
     const vtkm::cont::DataSet& input,
@@ -97,13 +103,19 @@ public:
   typedef TypeListTagScalarAll InputFieldTypeList;
 };
 
+/// \brief Construct the ContourTree for a 3D Mesh
+///
+/// Output field "saddlePeak" which is pairs of vertex ids indicating saddle and
+/// peak of contour
+/// Based on the algorithm presented in the paper:
+//  “Parallel Peak Pruning for Scalable SMP Contour Tree Computation.”
 class ContourTreeMesh3D : public vtkm::filter::FilterField<ContourTreeMesh3D>
 {
 public:
   VTKM_CONT
   ContourTreeMesh3D();
 
-  // Output field "saddlePeak" which is pairs of vertex ids indicating saddle and peak of contour
+  /// Output field "saddlePeak" which is pairs of vertex ids indicating saddle and peak of contour
   template <typename T, typename StorageType, typename DerivedPolicy, typename DeviceAdapter>
   VTKM_CONT vtkm::filter::ResultField DoExecute(
     const vtkm::cont::DataSet& input,

vtkm/filter/Entropy.h

@@ -23,9 +23,15 @@
 
 #include <vtkm/filter/FilterField.h>
 
-namespace vtkm {
-namespace filter {
+namespace vtkm
+{
+namespace filter
+{
 
+/// \brief Construct the entropy histogram of a given Field
+///
+/// Construct a histogram which is used to compute the entropy with a default of 10 bins
+///
 class Entropy : public vtkm::filter::FilterField<Entropy>
 {
 public:
@@ -34,28 +40,26 @@ public:
   Entropy();
 
   VTKM_CONT
-  void SetNumberOfBins(vtkm::Id count){ this->NumberOfBins = count; }
+  void SetNumberOfBins(vtkm::Id count) { this->NumberOfBins = count; }
 
-  template<typename T, typename StorageType, typename DerivedPolicy, typename DeviceAdapter>
-  VTKM_CONT
-  vtkm::filter::ResultField DoExecute(const vtkm::cont::DataSet& input,
-                                      const vtkm::cont::ArrayHandle<T, StorageType>& field,
-                                      const vtkm::filter::FieldMetadata& fieldMeta,
-                                      const vtkm::filter::PolicyBase<DerivedPolicy>& policy,
-                                      const DeviceAdapter& tag);
+  template <typename T, typename StorageType, typename DerivedPolicy, typename DeviceAdapter>
+  VTKM_CONT vtkm::filter::ResultField DoExecute(
+    const vtkm::cont::DataSet& input,
+    const vtkm::cont::ArrayHandle<T, StorageType>& field,
+    const vtkm::filter::FieldMetadata& fieldMeta,
+    const vtkm::filter::PolicyBase<DerivedPolicy>& policy,
+    const DeviceAdapter& tag);
 
 private:
-  vtkm::Id  NumberOfBins;
+  vtkm::Id NumberOfBins;
 };
 
-template<>
+template <>
 class FilterTraits<Entropy>
 {
 public:
   typedef TypeListTagScalarAll InputFieldTypeList;
 };
-
-
 }
 } // namespace vtkm::filter
 

vtkm/filter/ExternalFaces.h

@@ -30,6 +30,14 @@ namespace vtkm
 namespace filter
 {
 
+/// \brief  Extract external faces of a geometry
+///
+/// ExternalFaces is a filter that extracts all external faces from a
+/// data set. An external face is defined is defined as a face/side of a cell
+/// that belongs only to one cell in the entire mesh.
+/// @warning
+/// This filter is currently only supports propagation of point properties
+///
 class ExternalFaces : public vtkm::filter::FilterDataSet<ExternalFaces>
 {
 public:

vtkm/filter/ExtractGeometry.h

@@ -30,6 +30,21 @@ namespace vtkm
 namespace filter
 {
 
+/// \brief  Extract a subset of geometry based on an implicit function
+///
+/// Extracts from its input geometry all cells that are either
+/// completely inside or outside of a specified implicit function. Any type of
+/// data can be input to this filter.
+///
+/// To use this filter you must specify an implicit function. You must also
+/// specify whether to extract cells laying inside or outside of the implicit
+/// function. (The inside of an implicit function is the negative values
+/// region.) An option exists to extract cells that are neither inside or
+/// outside (i.e., boundary).
+///
+/// This differs from Clip in that Clip will subdivide boundary cells into new
+/// cells, while this filter will not, producing a more 'crinkly' output.
+///
 class ExtractGeometry : public vtkm::filter::FilterDataSet<ExtractGeometry>
 {
 public:

vtkm/filter/ExtractPoints.h

@@ -30,25 +30,34 @@ namespace vtkm
 {
 namespace filter
 {
-
+/// @brief Extract only points from a geometry using an implicit function
+///
+///
+/// Extract only the  points that are either inside or outside of a
+/// VTK-m implicit function. Examples include planes, spheres, boxes,
+/// etc.
+/// Note that while any geometry type can be provided as input, the output is
+/// represented by an explicit representation of points using
+/// vtkm::cont::CellSetSingleType
 class ExtractPoints : public vtkm::filter::FilterDataSet<ExtractPoints>
 {
 public:
   VTKM_CONT
   ExtractPoints();
 
-  // When CompactPoints is set, instead of copying the points and point fields
-  // from the input, the filter will create new compact fields without the unused elements
+  /// When CompactPoints is set, instead of copying the points and point fields
+  /// from the input, the filter will create new compact fields without the unused elements
   VTKM_CONT
   bool GetCompactPoints() const { return this->CompactPoints; }
   VTKM_CONT
   void SetCompactPoints(bool value) { this->CompactPoints = value; }
 
-  // Set the volume of interest to extract
+  /// Set the volume of interest to extract
   template <typename ImplicitFunctionType, typename DerivedPolicy>
   void SetImplicitFunction(const std::shared_ptr<ImplicitFunctionType>& func,
                            const vtkm::filter::PolicyBase<DerivedPolicy>& policy);
 
+  /// Set the volume of interest to extract
   template <typename ImplicitFunctionType>
   void SetImplicitFunction(const std::shared_ptr<ImplicitFunctionType>& func)
   {

vtkm/filter/ExtractStructured.h

@@ -28,7 +28,22 @@ namespace vtkm
 {
 namespace filter
 {
-
+/// \brief Select piece (e.g., volume of interest) and/or subsample structured points dataset
+///
+/// Select or subsample a portion of an input structured dataset. The selected
+/// portion of interested is referred to as the Volume Of Interest, or VOI.
+/// The output of this filter is a structured dataset. The filter treats input
+/// data of any topological dimension (i.e., point, line, plane, or volume) and
+/// can generate output data of any topological dimension.
+///
+/// To use this filter set the VOI ivar which are i-j-k min/max indices that
+/// specify a rectangular region in the data. (Note that these are 0-offset.)
+/// You can also specify a sampling rate to subsample the data.
+///
+/// Typical applications of this filter are to extract a slice from a volume
+/// for image processing, subsampling large volumes to reduce data size, or
+/// extracting regions of a volume with interesting data.
+///
 class ExtractStructured : public vtkm::filter::FilterDataSet<ExtractStructured>
 {
 public:
@@ -54,17 +69,22 @@ public:
   VTKM_CONT
   void SetVOI(const vtkm::RangeId3& voi) { this->VOI = voi; }
 
-  // Sampling rate
+  /// Get the Sampling rate
   VTKM_CONT
   vtkm::Id3 GetSampleRate() const { return this->SampleRate; }
+
+  /// Set the Sampling rate
   VTKM_CONT
   void SetSampleRate(vtkm::Id i, vtkm::Id j, vtkm::Id k) { this->SampleRate = vtkm::Id3(i, j, k); }
+
+  /// Set the Sampling rate
   VTKM_CONT
   void SetSampleRate(vtkm::Id3 sampleRate) { this->SampleRate = sampleRate; }
 
-  // Include the outer boundary on a subsample
+  /// Get if we should include the outer boundary on a subsample
   VTKM_CONT
   bool GetIncludeBoundary() { return this->IncludeBoundary; }
+  /// Set if we should include the outer boundary on a subsample
   VTKM_CONT
   void SetIncludeBoundary(bool value) { this->IncludeBoundary = value; }
 

vtkm/filter/Gradient.h

@@ -28,6 +28,7 @@ namespace vtkm
 namespace filter
 {
 
+/// \brief A general filter for gradient estimation.
 /// Estimates the gradient of a point field in a data set. The created gradient array
 /// can be determined at either each point location or at the center of each cell.
 ///

vtkm/filter/Histogram.h

@@ -27,7 +27,10 @@ namespace vtkm
 {
 namespace filter
 {
-
+/// \brief Construct the histogram of a given Field
+///
+/// Construct a histogram with a default of 10 bins
+///
 class Histogram : public vtkm::filter::FilterField<Histogram>
 {
 public:

vtkm/filter/MarchingCubes.h

@@ -28,16 +28,13 @@ namespace vtkm
 {
 namespace filter
 {
+/// \brief generate isosurface(s) from a Volume
 
-/*
-* Outstanding issues:
-* 1. The output is a proper dataset, which means:
-*     It needs a cell set
-*     It needs a coordinate system
-*
-*
-*/
-
+/// Takes as input a volume (e.g., 3D structured point set) and generates on
+/// output one or more isosurfaces.
+/// Multiple contour values must be specified to generate the isosurfaces.
+/// @warning
+/// This filter is currently only supports 3D volumes.
 class MarchingCubes : public vtkm::filter::FilterDataSetWithField<MarchingCubes>
 {
 public:
@@ -62,6 +59,10 @@ public:
   VTKM_CONT
   vtkm::Float64 GetIsoValue(vtkm::Id index) const;
 
+  /// Set/Get whether the points generated should be unique for every triangle
+  /// or will duplicate points be merged together. Duplicate points are identified
+  /// by the unique edge it was generated from.
+  ///
   VTKM_CONT
   void SetMergeDuplicatePoints(bool on) { this->Worklet.SetMergeDuplicatePoints(on); }
 

vtkm/filter/Mask.h

@@ -29,7 +29,9 @@ namespace vtkm
 {
 namespace filter
 {
-
+/// \brief Subselect cells using a stride
+///
+/// Extract only every Nth cell where N is equal to a stride value
 class Mask : public vtkm::filter::FilterDataSet<Mask>
 {
 public:

vtkm/filter/MaskPoints.h

@@ -30,6 +30,9 @@ namespace vtkm
 namespace filter
 {
 
+/// \brief Subselect points using a stride
+///
+/// Extract only every Nth point where N is equal to a stride value
 class MaskPoints : public vtkm::filter::FilterDataSet<MaskPoints>
 {
 public:

vtkm/filter/PointAverage.h

@@ -28,7 +28,12 @@ namespace vtkm
 {
 namespace filter
 {
-
+/// \brief Cell to Point interpolation filter.
+///
+/// PointAverage is a filter that transforms cell data (i.e., data
+/// specified per cell) into point data (i.e., data specified at cell
+/// points). The method of transformation is based on averaging the data
+/// values of all cells using a particular point.
 class PointAverage : public vtkm::filter::FilterCell<PointAverage>
 {
 public:

vtkm/filter/PointElevation.h

@@ -28,7 +28,13 @@ namespace vtkm
 {
 namespace filter
 {
-
+/// \brief  generate a scalar field along a specified direction
+///
+/// Generate scalar field from a dataset.
+/// The scalar field values lie within a user specified range, and
+/// are generated by computing a projection of each dataset point onto
+/// a line. The line can be oriented arbitrarily. A typical example is
+/// to generate scalars based on elevation or height above a plane.
 class PointElevation : public vtkm::filter::FilterField<PointElevation>
 {
 public:

vtkm/filter/SurfaceNormals.h

@@ -27,6 +27,8 @@ namespace vtkm
 namespace filter
 {
 
+/// \brief compute normals for polygonal mesh
+///
 /// Compute surface normals on points and/or cells of a polygonal dataset.
 /// The cell normals are faceted and are computed based on the plane where a
 /// face lies. The point normals are smooth normals, computed by averaging

vtkm/filter/Threshold.h

@@ -29,6 +29,15 @@ namespace vtkm
 namespace filter
 {
 
+/// \brief Extracts cells where scalar value in cell satisfies threshold criterion
+///
+/// Extracts all cells from any dataset type that
+/// satisfy a threshold criterion. A cell satisfies the criterion if the
+/// scalar value of every point or cell satisfies the criterion. The
+/// criterion takes the form of between two values. The output of this
+/// filter is an permutation of the input dataset.
+///
+/// You can threshold either on point or cell fields
 class Threshold : public vtkm::filter::FilterDataSetWithField<Threshold>
 {
 public:

vtkm/filter/VertexClustering.h

@@ -29,6 +29,34 @@ namespace vtkm
 namespace filter
 {
 
+/// \brief Reduce the number of triangles in a mesh
+///
+/// VertexClustering is a filter to reduce the number of triangles in a
+/// triangle mesh, forming a good approximation to the original geometry. The
+/// input must be a dataset that only contains triangles.
+///
+/// The general approach of the algorithm is to cluster vertices in a uniform
+/// binning of space, accumulating to an average point within each bin. In
+/// more detail, the algorithm first gets the bounds of the input poly data.
+/// It then breaks this bounding volume into a user-specified number of
+/// spatial bins.  It then reads each triangle from the input and hashes its
+/// vertices into these bins. Then, if 2 or more vertices of
+/// the triangle fall in the same bin, the triangle is dicarded.  If the
+/// triangle is not discarded, it adds the triangle to the list of output
+/// triangles as a list of vertex identifiers.  (There is one vertex id per
+/// bin.)  After all the triangles have been read, the representative vertex
+/// for each bin is computed.  This determines the spatial location of the
+/// vertices of each of the triangles in the output.
+///
+/// To use this filter, specify the divisions defining the spatial subdivision
+/// in the x, y, and z directions. Compared to algorithms such as
+/// vtkQuadricClustering, a significantly higher bin count is recommended as it
+/// doesn't increase the computation or memory of the algorithm and will produce
+/// significantly better results.
+///
+/// @warning
+/// This filter currently doesn't propagate cell or point fields
+
 class VertexClustering : public vtkm::filter::FilterDataSet<VertexClustering>
 {
 public: