diff --git a/alg/teca_2d_component_area.h b/alg/teca_2d_component_area.h
index 5a9d57e6a..54f4a2e42 100644
--- a/alg/teca_2d_component_area.h
+++ b/alg/teca_2d_component_area.h
@@ -10,40 +10,40 @@
 
 TECA_SHARED_OBJECT_FORWARD_DECL(teca_2d_component_area)
 
-/// an algorithm that computes the area of labeled regions
+/// An algorithm that computes the areas of labeled regions
 /**
-Given a set of labels on a Cartesian mesh, the algorithm computes the area of
-each region. Regions are identified by assigning a unique integer value to each
-mesh point that belongs in the region. The component_variable property names
-the variable containing the region labels.
-
-if the region labels start at 0 and are contiguous then an optimization can be
-used. Set contiguous_component_ids property to enable the optimization. Note that
-TECA's connected component labeler assigns the background (i.e. cells not inside
-the segmentation) the label 0. One can identify the background region and area
-via this label. When processing data generated outside of TECA it might be
-necessary to supply the background label. Use -2 if there is no background.
-
-the input dataset is passed through and the results of the calculations are
-stored in the output dataset metadata in the following keys:
-
-    number_of_components - number of component ids for which area was
-                           computed. Note that this can include a background
-                           component i.e. for cells outside of the segmentation.
-
-    component_ids - a vector containing the label of each component. This is
-                    always starts with 0, where the label 0 identifies cells
-                    out side of the segmentation, and ranges up to
-                    number_of_components - 1, where the labels from 1 up to
-                    number_of_components - 1 identify connected regions of
-                    cells inside the segmentation.
-
-    component_area - a vector containing the area for the corresponding entry
-                     in the component_ids array.
-
-    background_id - the label used for cells outside of the segmentation,
-                    i.e. the background. This can be used to skip processing
-                    of the background when desirable.
+ * Given a set of labels on a Cartesian mesh, the algorithm computes the area
+ * of each region. Regions are identified by assigning a unique integer value
+ * to each mesh point that belongs in the region. The component_variable
+ * property names the variable containing the region labels.
+ *
+ * if the region labels start at 0 and are contiguous then an optimization can
+ * be used. Set contiguous_component_ids property to enable the optimization.
+ * Note that TECA's connected component labeler assigns the background (i.e.
+ * cells not inside the segmentation) the label 0. One can identify the
+ * background region and area via this label. When processing data generated
+ * outside of TECA it might be necessary to supply the background label. Use -2
+ * if there is no background.
+ *
+ * the input dataset is passed through and the results of the calculations are
+ * stored in the output dataset metadata in the following keys:
+ *
+ *  | name                 | description |
+ *  | ----                 | ----------- |
+ *  | number_of_components | number of component ids for which area was |
+ *  |                      | computed. Note that this can include a background |
+ *  |                      | component i.e. for cells outside of the segmentation. |
+ *  | component_ids        | a vector containing the label of each component. This is |
+ *  |                      | always starts with 0, where the label 0 identifies |
+ *  |                      | cells out side of the segmentation, and ranges up |
+ *  |                      | to number_of_components - 1, where the labels from |
+ *  |                      | 1 up to number_of_components - 1 identify |
+ *  |                      | connected regions of cells inside the segmentation. |
+ *  | component_area       | a vector containing the area for the corresponding |
+ *  |                      |  entry in the component_ids array. |
+ *  | background_id        | the label used for cells outside of the segmentation, |
+ *  |                      | i.e. the background. This can be used to skip processing |
+ *  |                      | of the background when desirable. |
 */
 class teca_2d_component_area : public teca_algorithm
 {
@@ -53,23 +53,40 @@ class teca_2d_component_area : public teca_algorithm
     TECA_ALGORITHM_CLASS_NAME(teca_2d_component_area)
     ~teca_2d_component_area();
 
-    // report/initialize to/from Boost program options objects.
+    /** @name program_options
+     * report/initialize to/from Boost program options objects.
+     */
+    ///@{
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
+    ///@}
 
-    // set the name of the input array
+    /** @name component_variable
+     * Sets the name of the array containing component labels to compute the
+     * area of.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, component_variable)
+    ///@}
 
-    // set this only if you know for certain that label ids are contiguous and
-    // start at 0. this enables use of a faster implementation.
+    /** @name contiguous_component_ids
+     * set this only if you know for certain that label ids are contiguous and
+     * start at 0. this enables use of a faster implementation.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(int, contiguous_component_ids)
-
-    // set this to override the component label used for background. By default
-    // this is set to -1 to indicate that the value should be obtained from the
-    // metadata key `background_id`.  Note that TECA's connected component
-    // labeler uses the id 0 for the background and passes this in a metadata
-    // key and as a result no action is required.
+    ///@}
+
+    /** @name background_id
+     * set this to override the component label used for background. By default
+     * this is set to -1 to indicate that the value should be obtained from the
+     * metadata key `background_id`.  Note that TECA's connected component
+     * labeler uses the id 0 for the background and passes this in a metadata
+     * key and as a result no action is required.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(long, background_id)
+    ///@}
 
 protected:
     teca_2d_component_area();
diff --git a/alg/teca_apply_binary_mask.h b/alg/teca_apply_binary_mask.h
index 3763e274e..ceeed4040 100644
--- a/alg/teca_apply_binary_mask.h
+++ b/alg/teca_apply_binary_mask.h
@@ -43,16 +43,14 @@ class teca_apply_binary_mask : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    /** @anchor mask_variable
-     * @name mask_variable
+    /** @name mask_variable
      * set the name of the variable containing the mask values
      */
     ///@{
     TECA_ALGORITHM_PROPERTY(std::string, mask_variable)
     ///@}
 
-    /** @anchor masked_variable
-     * @name masked_variable
+    /** @name masked_variable
      * A list of of variables to apply the mask to. If empty no arrays will be
      * requested, and no variables will be masked
      */
@@ -60,8 +58,7 @@ class teca_apply_binary_mask : public teca_algorithm
     TECA_ALGORITHM_VECTOR_PROPERTY(std::string, masked_variable)
     ///@}
 
-    /** @anchor output_variable_prefix
-     * @name output_variable_prefix
+    /** @name output_variable_prefix
      * A prefix for the names of the variables that have been masked.  If this
      * is empty masked data replaces its input, otherwise input data is
      * preserved and masked data is added.
diff --git a/alg/teca_bayesian_ar_detect.h b/alg/teca_bayesian_ar_detect.h
index b8fe86ed8..aecbd9411 100644
--- a/alg/teca_bayesian_ar_detect.h
+++ b/alg/teca_bayesian_ar_detect.h
@@ -10,36 +10,35 @@
 
 TECA_SHARED_OBJECT_FORWARD_DECL(teca_bayesian_ar_detect)
 
-/// TECA BARD atmospheric river detector
+/// The TECA BARD atmospheric river detector.
 /**
-Given a point wise IVT (integrated vapor transport) field and a training
-parameter table computes the point wise probability of an atmospheric river
-using the TECA BARD algorithm.
-
-Required inputs:
-
-    1. IVT (integrated vapor transport) array on a Cartesian nesh.
-    2. a compatible parameter table. columns of which are : min IVT,
-       component area, HWHM lattitude
-
-The names of the input varibale and columns can be specified at run time
-through algorithm properties.
-
-Produces:
-
-    A Cartesian mesh with probability of an AR stored in the point centered
-    array named "ar_probability". The diagnostic quantites "ar_count" amd
-    "parameter_table_row" are stored in information arrays.
-
-For more information see:
-
-O’Brien, T. A., Risser, M. D., Loring, B., Elbashandy, A. A., Krishnan, H.,
-Johnson, J., Patricola, C. M., O’Brien, J. P., Mahesh, A., Arriaga Ramirez,
-S., Rhoades, A. M., Charn, A., Inda Díaz, H., & Collins, W. D. (2020).
-Detection of atmospheric rivers with inline uncertainty quantification:
-TECA-BARD v1.0.1. Geoscientific Model Development, 13(12), 6131–6148.
-https://doi.org/10.5194/gmd-13-6131-2020
-
+ * Given a point wise IVT (integrated vapor transport) field and a training
+ * parameter table computes the point wise probability of an atmospheric river
+ * using the TECA BARD algorithm.
+ *
+ * Required inputs:
+ *
+ *     1. IVT (integrated vapor transport) array on a Cartesian nesh.
+ *     2. a compatible parameter table. columns of which are : min IVT,
+ *        component area, HWHM lattitude
+ *
+ * The names of the input varibale and columns can be specified at run time
+ * through algorithm properties.
+ *
+ * Produces:
+ *
+ *     A Cartesian mesh with probability of an AR stored in the point centered
+ *     array named "ar_probability". The diagnostic quantites "ar_count" amd
+ *     "parameter_table_row" are stored in information arrays.
+ *
+ * For more information see:
+ *
+ * O’Brien, T. A., Risser, M. D., Loring, B., Elbashandy, A. A., Krishnan, H.,
+ * Johnson, J., Patricola, C. M., O’Brien, J. P., Mahesh, A., Arriaga Ramirez,
+ * S., Rhoades, A. M., Charn, A., Inda Díaz, H., & Collins, W. D. (2020).
+ * Detection of atmospheric rivers with inline uncertainty quantification:
+ * TECA-BARD v1.0.1. Geoscientific Model Development, 13(12), 6131–6148.
+ * https://doi.org/10.5194/gmd-13-6131-2020
 */
 class teca_bayesian_ar_detect : public teca_algorithm
 {
@@ -54,32 +53,54 @@ class teca_bayesian_ar_detect : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    // set the name of the input array
+    /** @name ivt_variable
+     * Sets the name of the array containing the IVT field to detect ARs in.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, ivt_variable)
+    ///@}
 
-    // set the names of columns in the parameter table.
+    /** @name min_ivt_variable
+     * Set the names of the minimum IVT column in the parameter table.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, min_ivt_variable)
+    ///@}
+
+    /** @name min_component_area_variable
+     * Set the names of the minimum area column in the parameter table.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, min_component_area_variable)
+    ///@}
+
+    /** @name hwhm_latitude_variable
+     * Set the names of the HWHM column in the parameter table.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, hwhm_latitude_variable)
+    ///@}
 
-    /** @anchor probability variable
-     * @name probability variable
+    /** @name probability variable
      * Set the name of the variable to store output probability as.
      */
     ///@{
     TECA_ALGORITHM_PROPERTY(std::string, ar_probability_variable)
     ///@}
 
-    // set/get the number of threads in the pool. setting
-    // to -1 results in a thread per core factoring in all MPI
-    // ranks running on the node. the default is -1.
+    /** Set the number of threads in the pool. Setting to -1 results in a
+     * thread per core factoring in all MPI ranks running on the node. the
+     * default is -1.
+     */
     void set_thread_pool_size(int n_threads);
+
+    /// Get the number of threads in the pool.
     unsigned int get_thread_pool_size() const noexcept;
 
-    // override the input connections because we are going to
-    // take the first input and use it to generate metadata.
-    // the second input then becomes the only one the pipeline
-    // knows about.
+    /** override the input connections because we are going to take the first
+     * input and use it to generate metadata.  the second input then becomes
+     * the only one the pipeline knows about.
+     */
     void set_input_connection(unsigned int id,
         const teca_algorithm_output_port &port) override;
 
diff --git a/alg/teca_bayesian_ar_detect_parameters.h b/alg/teca_bayesian_ar_detect_parameters.h
index e286d129b..518305301 100644
--- a/alg/teca_bayesian_ar_detect_parameters.h
+++ b/alg/teca_bayesian_ar_detect_parameters.h
@@ -22,12 +22,16 @@ class teca_bayesian_ar_detect_parameters : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    // control the number of rows copied into the table.  The rows are
-    // copied in sequential order starting from row zero. The default value
-    // of -1 is used to serve all rows. See also get_parameter_table_size.
+    /** @name number_of_rows
+     * control the number of rows copied into the table.  The rows are copied
+     * in sequential order starting from row zero. The default value of -1 is
+     * used to serve all rows. See also get_parameter_table_size.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(long, number_of_rows)
+    ///@}
 
-    // return the number of rows in the internal parameter table.
+    /// return the number of rows in the internal parameter table.
     unsigned long get_parameter_table_size();
 
 protected:
diff --git a/alg/teca_binary_segmentation.h b/alg/teca_binary_segmentation.h
index 983a497fb..138a28b03 100644
--- a/alg/teca_binary_segmentation.h
+++ b/alg/teca_binary_segmentation.h
@@ -10,17 +10,17 @@
 
 TECA_SHARED_OBJECT_FORWARD_DECL(teca_binary_segmentation)
 
-/// an algorithm that computes a binary segmentation
+/// An algorithm that computes a binary segmentation.
 /**
-an algorithm that computes a binary segmentation for 1D, 2D, and 3D data. The
-segmentation is computed using threshold operation where values in a range
-(low, high] are in the segmentation (assigned 1). Values outside the range
-are outside of the segmentation (assigned 0).
-
-The algorithm has 2 modes, BY_VALUE and BY_PERCENTILE. In the BY_VALUE mode,
-the test for inclusion is applied on the raw data. In the BY_PERCENTILE mode
-the range is given in percentiles and each data point is converted to a
-percentile before applying the test for inclusion.
+ * an algorithm that computes a binary segmentation for 1D, 2D, and 3D data.
+ * The segmentation is computed using threshold operation where values in a
+ * range (low, high] are in the segmentation (assigned 1). Values outside the
+ * range are outside of the segmentation (assigned 0).
+ *
+ * The algorithm has 2 modes, BY_VALUE and BY_PERCENTILE. In the BY_VALUE mode,
+ * the test for inclusion is applied on the raw data. In the BY_PERCENTILE mode
+ * the range is given in percentiles and each data point is converted to a
+ * percentile before applying the test for inclusion.
 */
 class teca_binary_segmentation : public teca_algorithm
 {
@@ -31,26 +31,59 @@ class teca_binary_segmentation : public teca_algorithm
     ~teca_binary_segmentation();
 
     // set the name of the output array to store the resulting segmentation in
+    /** @name segmentation_variable
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, segmentation_variable)
+    ///@}
+
 
     // set extra metadata for the segmentation variable
+    /** @name segmentation_variable_attributes
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(teca_metadata, segmentation_variable_attributes)
+    ///@}
+
 
-    // set the name of the input array to segment
+    /** @name threshold_variable
+     * set the name of the input array to segment
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, threshold_variable)
+    ///@}
 
-    // Set the threshold range. The defaults are (-infinity, infinity].
+    /** @name low_threshold_value
+     * Set the threshold range. The defaults are (-infinity, infinity].
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(double, low_threshold_value)
-    TECA_ALGORITHM_PROPERTY(double, high_threshold_value)
+    ///@}
 
-    // Set the threshold mode. In BY_PERCENTILE mode low and high thresholds
-    // define the percentiles (0 to 100) between which data is in the
-    // segmentation. default is BY_VALUE.
+    /** @name high_threshold_value
+     * Set the threshold range. The defaults are (-infinity, infinity].
+     */
+    ///@{
+    TECA_ALGORITHM_PROPERTY(double, high_threshold_value)
+    ///@}
+
+    /** @name threshold_mode
+     * Set the threshold mode. In BY_PERCENTILE mode low and high thresholds
+     * define the percentiles (0 to 100) between which data is in the
+     * segmentation. default is BY_VALUE.
+     */
+    ///@{
+    /// The threshold_mode modes
     enum {BY_VALUE=0, BY_PERCENTILE=1};
-    TECA_ALGORITHM_PROPERTY(int, threshold_mode);
 
+    TECA_ALGORITHM_PROPERTY(int, threshold_mode)
+
+    /// Set the threshold_mode to percentile.
     void set_threshold_by_percentile() { set_threshold_mode(BY_PERCENTILE); }
+
+    /// Set the threshold_mode to value.
     void set_threshold_by_value() { set_threshold_mode(BY_VALUE); }
+    ///@}
 
 protected:
     teca_binary_segmentation();
diff --git a/alg/teca_cartesian_mesh_regrid.h b/alg/teca_cartesian_mesh_regrid.h
index 201c7ef64..d67c5f7f0 100644
--- a/alg/teca_cartesian_mesh_regrid.h
+++ b/alg/teca_cartesian_mesh_regrid.h
@@ -4,7 +4,7 @@
 #include "teca_shared_object.h"
 #include "teca_algorithm.h"
 #include "teca_metadata.h"
-#include "teca_variant_array_fwd.h"
+#include "teca_variant_array.h"
 
 #include <string>
 #include <vector>
@@ -40,24 +40,21 @@ class teca_cartesian_mesh_regrid : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    /** @anchor array
-     * @name array
+    /** @name array
      * set the list of arrays to move from the source to the target
      */
     //@{
     TECA_ALGORITHM_VECTOR_PROPERTY(std::string, array)
     //@}
 
-    /** @anchor target_input
-     * @name target_input
+    /** @name target_input
      * set the input connection which provides the output geometry.
      */
     ///@{
     TECA_ALGORITHM_PROPERTY(int, target_input)
     ///@}
 
-    /** @anchor interpolation_mode
-     * @name interpolation_mode
+    /** @name interpolation_mode
      * set the interpolation mode used in transfering data between meshes of
      * differing resolution.  in nearest mode value at the nearest grid point
      * is used, in linear mode bi/tri linear interpolation is used.
diff --git a/alg/teca_cartesian_mesh_source.h b/alg/teca_cartesian_mesh_source.h
index e33296650..d357ad0ba 100644
--- a/alg/teca_cartesian_mesh_source.h
+++ b/alg/teca_cartesian_mesh_source.h
@@ -20,7 +20,7 @@ using field_generator_callback = std::function<p_teca_variant_array(
     const const_p_teca_variant_array &, double)>;
 
 /** An object that bundles field name, the metadata attributes needed for I/O,
- * and a field generator callback. Use this with ::append_field_generator
+ * and a field generator callback. Use this with append_field_generator
  */
 struct field_generator
 {
@@ -43,25 +43,24 @@ bool operator!=(const field_generator &l, const field_generator &r)
     return l.name != r.name;
 }
 
-
 /** @brief
  * An algorithm that generates a teca_cartesian_mesh of the requested
  * spatial and temporal dimensions with optional user defined fields.
  *
  * @details
  * User defined fields are specified by passing callbacks and metadata
- * via @ref field_generator and @ref append_field_generator
+ * via field_generator and append_field_generator
  *
  * The spatial and temporal dimensions are set by the combination of
- * @ref whole_extent and @ref bounds.
+ *  whole_extent and  bounds.
  *
  * The names of coordinate axes are set by the combination
- * of @ref x_axis_variable, @ref y_axis_variable, @ref z_axis_variable,
- * and @ref t_axis_variable
+ * of  x_axis_variable,  y_axis_variable,  z_axis_variable,
+ * and  t_axis_variable
  *
  * The units of the coordinate axes are set by the combination of
- * @ref x_axis_units, @ref y_axis_units, @ref z_axis_units, @ref calendar,
- * and @ref time_units.
+ *  x_axis_units,  y_axis_units,  z_axis_units,  calendar,
+ * and  time_units.
  */
 class teca_cartesian_mesh_source : public teca_algorithm
 {
@@ -76,8 +75,7 @@ class teca_cartesian_mesh_source : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    /** @anchor coordinate_type_code
-     * @name coordinate_type_code
+    /** @name coordinate_type_code
      * set/get the type code for generated coordinates. The default is a 64 bit
      * floating point type. Use teca_variant_array_code<NT>::get() to get
      * specific type codes for C++ POD types NT.
@@ -86,8 +84,7 @@ class teca_cartesian_mesh_source : public teca_algorithm
     TECA_ALGORITHM_PROPERTY(unsigned int, coordinate_type_code)
     ///@}
 
-    /** @anchor field_type_code
-     * @name field_type_code
+    /** @name field_type_code
      * set/get the type code for generated fields. The default is a 64 bit
      * floating point type. Use teca_variant_array_code<NT>::get() to get
      * specific type codes for C++ POD types NT.
@@ -96,8 +93,7 @@ class teca_cartesian_mesh_source : public teca_algorithm
     TECA_ALGORITHM_PROPERTY(unsigned int, field_type_code)
     ///@}
 
-    /** @anchor whole_extent
-     * @name whole_extent
+    /** @name whole_extent
      * set/get the global index space extent of the data.  the extents are
      * given by 8 values, 6 spatial plus 2 temporal, in the following order
      * [i0 i1 j0 j1 k0 k1 q0 q1] This should be the same on all ranks
@@ -106,7 +102,7 @@ class teca_cartesian_mesh_source : public teca_algorithm
     TECA_ALGORITHM_VECTOR_PROPERTY(unsigned long, whole_extent)
 
     /** Set the spatial extents from a metadata object following the
-     * conventions defined by the @ref teca_cf_reader. If three_d is true the
+     * conventions defined by the  teca_cf_reader. If three_d is true the
      * extents in the z-direction are copied, otherwise they are set to 0.
      * Returns zero if successful and non-zero if the supplied metadata is
      * missing any of the requisite information.
@@ -114,8 +110,7 @@ class teca_cartesian_mesh_source : public teca_algorithm
     int set_spatial_extents(const teca_metadata &md, bool three_d = true);
     ///@}
 
-    /** @anchor bounds
-     * @name bounds
+    /** @name bounds
      * set/get the global bounds of the data. the bounds are 8 values 6 spatial
      * plus 2 temporal in the following order. [x0 x1 y0 y1 z0 z1 t0 t1]
      * this should be the same on all ranks.
@@ -124,7 +119,7 @@ class teca_cartesian_mesh_source : public teca_algorithm
     TECA_ALGORITHM_VECTOR_PROPERTY(double, bound)
 
     /** Set the spatial bounds from a metadata object following the conventions
-     * defined by the @ref teca_cf_reader. Returns zero if successful and
+     * defined by the  teca_cf_reader. Returns zero if successful and
      * non-zero if the supplied metadata is missing any of the requisite
      * information.
      */
@@ -132,8 +127,7 @@ class teca_cartesian_mesh_source : public teca_algorithm
 
     ///@}
 
-    /** @anchor x_axis_variable
-     * @name x_axis_variable
+    /** @name x_axis_variable
      * set the name of the variable to use for the coordinate axes and
      * optionally associated attributes.
      */
@@ -141,21 +135,20 @@ class teca_cartesian_mesh_source : public teca_algorithm
     /** set the name of the t_axis_variable */
     void set_x_axis_variable(const std::string &name);
 
-    /** Set the name of the variable and its attributes. See @ref
+    /** Set the name of the variable and its attributes. See 
      * teca_array_attributes for more information.
      */
     void set_x_axis_variable(const std::string &name, const teca_metadata &atts);
 
     /** Set the name of the variable and its attributes using conventions
-     * defined by the @ref teca_cf_reader. Returns zero if successful and
+     * defined by the  teca_cf_reader. Returns zero if successful and
      * non-zero if the supplied metadata is missing any of the requisite
      * information.
      */
     int set_x_axis_variable(const teca_metadata &md);
     ///@}
 
-    /** @anchor y_axis_variable
-     * @name y_axis_variable
+    /** @name y_axis_variable
      * set the name of the variable to use for the coordinate axes and
      * optionally associated attributes.
      */
@@ -163,21 +156,20 @@ class teca_cartesian_mesh_source : public teca_algorithm
     /** set the name of the y_axis_variable */
     void set_y_axis_variable(const std::string &name);
 
-    /** Set the name of the variable and its attributes. See @ref
+    /** Set the name of the variable and its attributes. See 
      * teca_array_attributes for more information.
      */
     void set_y_axis_variable(const std::string &name, const teca_metadata &atts);
 
     /** Set the name of the variable and its attributes using conventions
-     * defined by the @ref teca_cf_reader. Returns zero if successful and
+     * defined by the  teca_cf_reader. Returns zero if successful and
      * non-zero if the supplied metadata is missing any of the requisite
      * information.
      */
     int set_y_axis_variable(const teca_metadata &md);
     ///@}
 
-    /** @anchor z_axis_variable
-     * @name z_axis_variable
+    /** @name z_axis_variable
      * set the name of the variable to use for the coordinate axes and
      * optionally associated attributes.
      */
@@ -185,21 +177,20 @@ class teca_cartesian_mesh_source : public teca_algorithm
     /** set the name of the z_axis_variable */
     void set_z_axis_variable(const std::string &name);
 
-    /** Set the name of the variable and its attributes. See @ref
+    /** Set the name of the variable and its attributes. See 
      * teca_array_attributes for more information.
      */
     void set_z_axis_variable(const std::string &name, const teca_metadata &atts);
 
     /** Set the name of the variable and its attributes using conventions
-     * defined by the @ref teca_cf_reader. Returns zero if successful and
+     * defined by the  teca_cf_reader. Returns zero if successful and
      * non-zero if the supplied metadata is missing any of the requisite
      * information.
      */
     int set_z_axis_variable(const teca_metadata &md);
     ///@}
 
-    /** @anchor t_axis_variable
-     * @name t_axis_variable
+    /** @name t_axis_variable
      * set the name of the variable to use for the coordinate axes and
      * optionally associated attributes.
      */
@@ -210,20 +201,20 @@ class teca_cartesian_mesh_source : public teca_algorithm
     /** Set the calendar, and time units of the t_axis_variable */
     void set_calendar(const std::string &calendar, const std::string &units);
 
-    /** Set the name of the variable and its attributes. See @ref
+    /** Set the name of the variable and its attributes. See 
      * teca_array_attributes for more information.
      */
     void set_t_axis_variable(const std::string &name,
         const teca_metadata &atts);
 
     /** Set the name of the variable and its attributes using conventions
-     * defined by the @ref teca_cf_reader. Returns zero if successful and
+     * defined by the  teca_cf_reader. Returns zero if successful and
      * non-zero if the supplied metadata is missing any of the requisite
      * information.
      */
     int set_t_axis_variable(const teca_metadata &md);
 
-    /** Set the time axis using coordinate conventions defined by the @ref
+    /** Set the time axis using coordinate conventions defined by the 
      * teca_cf_reader. When a time axis is provided values are served up from
      * the array rather than being generated. Execution control keys are also
      * made use of if present. Returns zero if successful and non-zero if the
@@ -236,15 +227,13 @@ class teca_cartesian_mesh_source : public teca_algorithm
      * keys are also made use of if present.
      */
     void set_t_axis(const p_teca_variant_array &t);
-
     ///@}
 
-    /** @anchor output_metadata
-     * @name output_metadata
+    /** @name output_metadata
      * Set the output metadata directly. The provided metadata must contain
-     * "coordinates" as defined by the @ref teca_cf_reader because these are
+     * "coordinates" as defined by the  teca_cf_reader because these are
      * required for mesh generation. Pipeline execution control keys as defined
-     * by @ref teca_index_executive are also required. Calendaring metadata is
+     * by  teca_index_executive are also required. Calendaring metadata is
      * recommended. A copy of the passed object is made but "variables" are
      * replaced with those generated by this class, if any. As a result be sure
      * to specifiy field generators before calling this method. Returns 0 if
@@ -255,8 +244,7 @@ class teca_cartesian_mesh_source : public teca_algorithm
     int set_output_metadata(const teca_metadata &md);
     ///@}
 
-    /** @anchor append_field_generator
-     * @name append_field_generator
+    /** @name append_field_generator
      * set a callback function f(x,y,z,t) that generates a field named name
      * x,y,z are coordinate axes in variant arrays, t is the double precision
      * time value.
@@ -266,8 +254,7 @@ class teca_cartesian_mesh_source : public teca_algorithm
         const teca_metadata &atts, field_generator_callback &callback);
     ///@}
 
-    /** @anchor field_generator
-     * @name field_generator
+    /** @name field_generator
      * Set/get the named callbacks that generate fields on the mesh. These
      * should be packaged in the field_generator struct so that field name
      * and attributes for I/O are provided together with the callback.
@@ -280,14 +267,19 @@ class teca_cartesian_mesh_source : public teca_algorithm
     teca_cartesian_mesh_source();
 
 private:
+    /// implements the report phase of pipeline execution
     teca_metadata get_output_metadata(unsigned int port,
         const std::vector<teca_metadata> &input_md) override;
 
+    /// implements the execute phase of pipeline execution
     const_p_teca_dataset execute(unsigned int port,
         const std::vector<const_p_teca_dataset> &input_data,
         const teca_metadata &request) override;
 
+    /// updates the modification state
     void set_modified() override;
+
+    /// clears cached metadata in response to modification of algorithm properties
     void clear_cached_metadata();
 
 private:
diff --git a/alg/teca_cartesian_mesh_subset.h b/alg/teca_cartesian_mesh_subset.h
index 3b2b2bf56..b4d9761ae 100644
--- a/alg/teca_cartesian_mesh_subset.h
+++ b/alg/teca_cartesian_mesh_subset.h
@@ -4,7 +4,7 @@
 #include "teca_shared_object.h"
 #include "teca_algorithm.h"
 #include "teca_metadata.h"
-#include "teca_variant_array_fwd.h"
+#include "teca_variant_array.h"
 
 #include <string>
 #include <vector>
@@ -13,13 +13,13 @@ TECA_SHARED_OBJECT_FORWARD_DECL(teca_cartesian_mesh_subset)
 
 /// applies a subset given in world coordinates to the upstream request
 /**
-an algorithm that applies a subset specified in
-world coordinates to upstream requests. the subset
-is specified as bounding box of the form [x_low to x_high,
-y_low to y_high, z_low to z_high]. The subset can be either
-the smallest subset containing the bounding box or the
-largest set contained by the bounding box, and is controled
-by the cover_bounds property.
+ * an algorithm that applies a subset specified in
+ * world coordinates to upstream requests. the subset
+ * is specified as bounding box of the form [x_low to x_high,
+ * y_low to y_high, z_low to z_high]. The subset can be either
+ * the smallest subset containing the bounding box or the
+ * largest set contained by the bounding box, and is controled
+ * by the cover_bounds property.
 */
 class teca_cartesian_mesh_subset : public teca_algorithm
 {
@@ -34,20 +34,26 @@ class teca_cartesian_mesh_subset : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    // define the bounding box of the subset
-    // this algorithm converts this into an
-    // extent into the upstream dataset.
-    TECA_ALGORITHM_PROPERTY(std::vector<double>, bounds);
+    /** @name bounds
+     * define the bounding box of the subset this algorithm converts this into
+     * an extent into the upstream dataset.
+     */
+    ///@{
+    TECA_ALGORITHM_PROPERTY(std::vector<double>, bounds)
 
     void set_bounds(double low_x, double high_x,
         double low_y, double high_y, double low_z, double high_z)
     { this->set_bounds({low_x, high_x, low_y, high_y, low_z, high_z}); }
+    ///@}
 
-    // control how bounds are converted. if true
-    // smallest subset covering the bounding box is
-    // used. if false the largest subset contained
-    // by the bounding box is used.
+    /** @name cover_bounds
+     * control how bounds are converted. if true smallest subset covering the
+     * bounding box is used. if false the largest subset contained by the
+     * bounding box is used.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(bool, cover_bounds)
+    ///@}
 
 protected:
     teca_cartesian_mesh_subset();
diff --git a/alg/teca_component_area_filter.h b/alg/teca_component_area_filter.h
index f6c8e5a22..6ef2669c0 100644
--- a/alg/teca_component_area_filter.h
+++ b/alg/teca_component_area_filter.h
@@ -12,29 +12,29 @@ TECA_SHARED_OBJECT_FORWARD_DECL(teca_component_area_filter)
 
 /// An algorithm that applies a mask based on connected component area
 /**
-The filter masks the regions identified by an integer label that are outside
-the range bracketed by the 'low_area_threshold' and 'high_area_threshold'
-properties. These default to -inf and +inf, hence by default no regions are
-masked. The mask value may be set by the 'mask_value' property which defaults
-to '0'.
-
-The filter expects an integer field containing connected component labels.
-This field is named by the 'component_variable' property. Additionally a list
-of label ids and coresponding areas is expected in the dataset metadata. The
-properties 'component_ids_key' and 'component_area_key' identify the latter
-metadata. These default to the names used by the 'teca_2d_component_area'
-algotihm, 'component_ids' and 'component_area'.
-
-Applying the 'teca_connected_component' algorithm followed by the
-'teca_2d_component_area' algorithm is the easiest way to get valid inputs for
-the 'component_area_filter'.
-
-The filtered coomponent ids are put in the output dataset along with the
-updated lists of valid component ids and component area metadata keys. By
-default the filtered data replaces the input data in the output. However, the
-input data can be retained by setting the 'variable_post_fix' property, a
-string that will be appended to the names of the filtered component array and
-metadata keys.
+ * The filter masks the regions identified by an integer label that are outside
+ * the range bracketed by the 'low_area_threshold' and 'high_area_threshold'
+ * properties. These default to -inf and +inf, hence by default no regions are
+ * masked. The mask value may be set by the 'mask_value' property which
+ * defaults to '0'.
+ *
+ * The filter expects an integer field containing connected component labels.
+ * This field is named by the 'component_variable' property. Additionally a
+ * list of label ids and coresponding areas is expected in the dataset
+ * metadata. The properties 'component_ids_key' and 'component_area_key'
+ * identify the latter metadata. These default to the names used by the
+ * 'teca_2d_component_area' algotihm, 'component_ids' and 'component_area'.
+ *
+ * Applying the 'teca_connected_component' algorithm followed by the
+ * 'teca_2d_component_area' algorithm is the easiest way to get valid inputs
+ * for the 'component_area_filter'.
+ *
+ * The filtered coomponent ids are put in the output dataset along with the
+ * updated lists of valid component ids and component area metadata keys. By
+ * default the filtered data replaces the input data in the output. However,
+ * the input data can be retained by setting the 'variable_post_fix' property,
+ * a string that will be appended to the names of the filtered component array
+ * and metadata keys.
 */
 class teca_component_area_filter : public teca_algorithm
 {
@@ -51,43 +51,78 @@ class teca_component_area_filter : public teca_algorithm
 
     // set the name of the input array containing connected
     // component labels
+    /** @name component_variable
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, component_variable)
+    ///@}
 
-    // set the name of the dataset metadata key holding the number of
-    // components left after the filter is applied
+    /** @name number_of_components_key
+     * set the name of the dataset metadata key holding the number of
+     * components left after the filter is applied
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, number_of_components_key)
+    ///@}
 
-    // set the name of the dataset metadata key holding connected component
-    // label ids
+    /** @name component_ids_key
+     * set the name of the dataset metadata key holding connected component
+     * label ids
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, component_ids_key)
+    ///@}
 
-    // set the name of the dataset metadata key holding connected component
-    // areas
+    /** @name component_area_key
+     * set the name of the dataset metadata key holding connected component
+     * areas
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, component_area_key)
-
-    // set this to be the default label id for the filtered out component
-    // areas. This will typically correspond to the label used for cells
-    // outside of the segmentation (i.e. in the background). One can use this
-    // property to override the mask value.  The default mask value is '-1'
-    // which results in aquiring the mask value from input metadata key
-    // `background_id`. Use -2 to specify no background label.
+    ///@}
+
+    /** @name mask_value
+     * set this to be the default label id for the filtered out component
+     * areas. This will typically correspond to the label used for cells
+     * outside of the segmentation (i.e. in the background). One can use this
+     * property to override the mask value.  The default mask value is '-1'
+     * which results in aquiring the mask value from input metadata key
+     * `background_id`. Use -2 to specify no background label.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(long, mask_value)
+    ///@}
 
-    // set the range identifying values to area filter.
-    // The defaults are (-infinity, infinity].
+    /** @name low_area_threshold
+     * set the range identifying values to area filter.  The defaults are
+     * (-infinity, infinity].
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(double, low_area_threshold)
-    TECA_ALGORITHM_PROPERTY(double, high_area_threshold)
+    ///@}
 
-    // a string to be appended to the name of the output variable.
-    // setting this to an empty string will result in the masked array
-    // replacing the input array in the output. default is an empty
-    // string ""
+    /** @name high_area_threshold
+     */
+    ///@{
+    TECA_ALGORITHM_PROPERTY(double, high_area_threshold)
+    ///@}
+
+    /** @name variable_post_fix
+     * a string to be appended to the name of the output variable.  setting
+     * this to an empty string will result in the masked array replacing the
+     * input array in the output. default is an empty string ""
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, variable_post_fix)
+    ///@}
 
-    // set this only if you know for certain that label ids
-    // are contiguous and start at 0. this enables use of a
-    // faster implementation.
+    /** @name contiguous_component_ids
+     * set this only if you know for certain that label ids are contiguous and
+     * start at 0. this enables use of a faster implementation.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(int, contiguous_component_ids)
+    ///@}
 
 protected:
     teca_component_area_filter();
diff --git a/alg/teca_connected_components.h b/alg/teca_connected_components.h
index 0f188f7e0..693ffa1b4 100644
--- a/alg/teca_connected_components.h
+++ b/alg/teca_connected_components.h
@@ -12,35 +12,35 @@ TECA_SHARED_OBJECT_FORWARD_DECL(teca_connected_components)
 
 /// an algorithm that computes connected component labeling
 /**
-an algorithm that computes connected component labeling for 1D, 2D, and 3D
-data. The components are computed from a binary segmentation provided on the
-input.
-
-the input binary segmentation is labeled and stored in a variable named by the
-component_variable property. the component ids are added to the output
-dataset metadata in an key named 'component_ids', and the number of components
-is stored in a key named 'number_of_components'. These keys facilitate further
-processing as one need not scan the labeled data to get the list of label ids.
-
-The cells outside of the segmentation (i.e. the background) are always assigned
-the label 0. The cells belonging to connected regions inside the segmentation
-are labeled starting from 1 up to number_of_components - 1.
-
-output keys:
-
-    number_of_components - number of component ids found. this will always be
-                           at least 1 long as the cells outside the segmentation
-                           are assigned the label 0.
-
-    component_ids - a vector containing the label of each component. This is
-                    always starts with 0, where the label 0 identifies cells
-                    out side of the segmentation, and ranges up to
-                    number_of_components - 1, where the labels from 1 up to
-                    number_of_components - 1 identify connected regions of
-                    cells inside the segmentation.
-
-    background_id - the label used for cells outside of the segmentation,
-                    i.e. the background. always 0.
+ * an algorithm that computes connected component labeling for 1D, 2D, and 3D
+ * data. The components are computed from a binary segmentation provided on the
+ * input.
+ *
+ * the input binary segmentation is labeled and stored in a variable named by the
+ * component_variable property. the component ids are added to the output
+ * dataset metadata in an key named 'component_ids', and the number of components
+ * is stored in a key named 'number_of_components'. These keys facilitate further
+ * processing as one need not scan the labeled data to get the list of label ids.
+ *
+ * The cells outside of the segmentation (i.e. the background) are always assigned
+ * the label 0. The cells belonging to connected regions inside the segmentation
+ * are labeled starting from 1 up to number_of_components - 1.
+ *
+ * output keys:
+ *
+ *  | name                 | description |
+ *  | ----                 | ----------- |
+ *  | number_of_components | number of component ids found. this will always be |
+ *  |                      | at least 1 long as the cells outside the segmentation |
+ *  |                      | are assigned the label 0. |
+ *  | component_ids | a vector containing the label of each component. This is |
+ *  |               | always starts with 0, where the label 0 identifies cells |
+ *  |               | out side of the segmentation, and ranges up to |
+ *  |               | number_of_components - 1, where the labels from 1 up to |
+ *  |               | number_of_components - 1 identify connected regions of |
+ *  |               | cells inside the segmentation. |
+ *  | background_id | the label used for cells outside of the segmentation, |
+ *  |               | i.e. the background. always 0. |
 */
 class teca_connected_components : public teca_algorithm
 {
diff --git a/alg/teca_dataset_diff.h b/alg/teca_dataset_diff.h
index 7fe64dc50..881b928f6 100644
--- a/alg/teca_dataset_diff.h
+++ b/alg/teca_dataset_diff.h
@@ -18,16 +18,14 @@ TECA_SHARED_OBJECT_FORWARD_DECL(teca_dataset_diff)
 
 /// compute the element wise difference between to datasets
 /**
-a two input algorithm that compares datasets by examining each
-element of their contained arrays. a threshold is used to detect
-when an element is different. a report containing the string FAIL
-is issued to stderr stream when a difference is detected. this
-algorithm is the core of TECA's regression test suite.
-
-by convention the first input produces the reference dataset,
-and the second input produces the dataset to validate. this is
-primarilly to support map-reduce implementation where after
-the reduction only rank 0 has data.
+ * a two input algorithm that compares datasets by examining each element of their
+ * contained arrays. a threshold is used to detect when an element is different. a
+ * report containing the string FAIL is issued to stderr stream when a difference
+ * is detected. this algorithm is the core of TECA's regression test suite.
+ *
+ * by convention the first input produces the reference dataset, and the second
+ * input produces the dataset to validate. this is primarilly to support
+ * map-reduce implementation where after the reduction only rank 0 has data.
 */
 class teca_dataset_diff : public teca_algorithm
 {
@@ -41,15 +39,23 @@ class teca_dataset_diff : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    // Relative tolerance below which two floating-point numbers a and b are
-    // considered equal. if |a - b| <= max(|a|,|b|)*tol then a is equal to b.
-    // the relative tolerance is used with numbers not close to zero.
+    /** @name relative_tolerance
+     * Relative tolerance below which two floating-point numbers a and b are
+     * considered equal. if |a - b| <= max(|a|,|b|)*tol then a is equal to b.
+     * the relative tolerance is used with numbers not close to zero.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(double, relative_tolerance)
-
-    // The absolute tolerance below which two floating point numbers a and b are
-    // considered equal. if |a - b| <= tol then a is equal to b. The absolute
-    // tolerance is used with numbers close to zero.
+    ///@}
+
+    /** @name absolute_tolerance
+     * The absolute tolerance below which two floating point numbers a and b
+     * are considered equal. if |a - b| <= tol then a is equal to b. The
+     * absolute tolerance is used with numbers close to zero.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(double, absolute_tolerance)
+    ///@}
 
 protected:
     teca_dataset_diff();
diff --git a/alg/teca_derived_quantity.h b/alg/teca_derived_quantity.h
index 922a87691..40b7510b5 100644
--- a/alg/teca_derived_quantity.h
+++ b/alg/teca_derived_quantity.h
@@ -3,7 +3,7 @@
 
 #include "teca_programmable_algorithm.h"
 #include "teca_metadata.h"
-#include "teca_dataset_fwd.h"
+#include "teca_dataset.h"
 #include "teca_shared_object.h"
 
 #include <string>
@@ -13,14 +13,13 @@ TECA_SHARED_OBJECT_FORWARD_DECL(teca_derived_quantity)
 
 /// a programmable algorithm specialized for simple array based computations
 /**
-A programmable algorithm specialized for simple array based
-computations. A user provided callable(see set execute_callback)
-which operates on one or more arrays(the dependent variables) to
-produce a new array (the derived quantity). The purpose of this
-class is to implement the request and report phases of the pipeline
-consistently for this common use case. An implementation specific
-context(operation_name) differentiates between multiple instances
-in the same pipeline.
+ * A programmable algorithm specialized for simple array based computations. A
+ * user provided callable(see set execute_callback) which operates on one or more
+ * arrays(the dependent variables) to produce a new array (the derived quantity).
+ * The purpose of this class is to implement the request and report phases of the
+ * pipeline consistently for this common use case. An implementation specific
+ * context(operation_name) differentiates between multiple instances in the same
+pipeline.
 */
 class teca_derived_quantity : public teca_programmable_algorithm
 {
diff --git a/alg/teca_descriptive_statistics.h b/alg/teca_descriptive_statistics.h
index b426dca64..416476c1e 100644
--- a/alg/teca_descriptive_statistics.h
+++ b/alg/teca_descriptive_statistics.h
@@ -12,8 +12,8 @@ TECA_SHARED_OBJECT_FORWARD_DECL(teca_descriptive_statistics)
 
 /// compute descriptive statistics over a set of arrays.
 /**
-compute the min, max, avg, median, standard deviation of a
-set of named arrays. the results are returned in a table.
+ * compute the min, max, avg, median, standard deviation of a set of named
+ * arrays. the results are returned in a table.
 */
 class teca_descriptive_statistics : public teca_algorithm
 {
diff --git a/alg/teca_elevation_mask.h b/alg/teca_elevation_mask.h
index dc9c4b4c6..fea8a7fbf 100644
--- a/alg/teca_elevation_mask.h
+++ b/alg/teca_elevation_mask.h
@@ -22,9 +22,9 @@ TECA_SHARED_OBJECT_FORWARD_DECL(teca_elevation_mask)
  * that is 1 where the 3D point is on or above the surface of the Earth and 0
  * where it is below.
  *
- * The name of the 3D height field is specified by the @ref mesh_height_variable
+ * The name of the 3D height field is specified by the  mesh_height_variable
  * property. The name of the 2D height field conntaining elveation of the
- * Earth's surface is specified by the @ref surface_elevation_variable property.
+ * Earth's surface is specified by the  surface_elevation_variable property.
  *
  * The 3D mesh height field must be provided on input 0, and the 2D surface
  * height field on input 1. Use the mask_names property to name the output
@@ -56,30 +56,30 @@ class teca_elevation_mask : public teca_algorithm
     TECA_ALGORITHM_CLASS_NAME(teca_elevation_mask)
     ~teca_elevation_mask();
 
-    // report/initialize to/from Boost program options
-    // objects.
+    /** @name program_options
+     * report/initialize to/from Boost program options objects.
+     */
+    ///@{
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
+    ///@}
 
-    /** @anchor mesh_height_variable
-     * @name algorithm property: mesh_height_variable
-     * set/get the name of the 3D height field
+    /** @name mesh_height_variable
+     * Set the name of the 3D height field
      */
     ///@{
     TECA_ALGORITHM_PROPERTY(std::string, mesh_height_variable)
     ///@}
 
-    /** @anchor surface_elevation_variable
-     * @name algorithm property: surface_elevation_variable
-     * set/get the name of the variable containing the elevation of the Earth's
+    /** @name surface_elevation_variable
+     * Set the name of the variable containing the elevation of the Earth's
      * surface.
      */
     ///@{
     TECA_ALGORITHM_PROPERTY(std::string, surface_elevation_variable)
     ///@}
 
-    /** @anchor mask_variables
-     * @name algorithm property: mask_variable
+    /** @name mask_variables
      * set the names of the variables to store the generated mask in
      * each variable will contain a reference to the mask
      */
diff --git a/alg/teca_evaluate_expression.h b/alg/teca_evaluate_expression.h
index 51cc3d1da..afbe546b6 100644
--- a/alg/teca_evaluate_expression.h
+++ b/alg/teca_evaluate_expression.h
@@ -41,18 +41,32 @@ class teca_evaluate_expression : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    // set/get the expression to evaluate
+    /** @name expression
+     * Set the expression to evaluate.
+     */
+    ///@{
+    /// Set the expression.
     void set_expression(const std::string &expr);
 
+    /// Get the expression.
     std::string get_expression()
     { return this->expression; }
+    ///@}
 
-    // set the name of the variable to store the result in
-    TECA_ALGORITHM_PROPERTY(std::string, result_variable);
+    /** @name result_variable
+     * set the name of the variable to store the result in
+     */
+    ///@{
+    TECA_ALGORITHM_PROPERTY(std::string, result_variable)
+    ///@}
 
-    // when set columns used in the calculation are removed
-    // from the output. default off.
+    /** @name remove_dependent_variables
+     * when set columns used in the calculation are removed from the output.
+     * default off.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(int, remove_dependent_variables)
+    ///@}
 
 protected:
     teca_evaluate_expression();
diff --git a/alg/teca_face_to_cell_centering.h b/alg/teca_face_to_cell_centering.h
index 563c9ae1f..458b7f9f0 100644
--- a/alg/teca_face_to_cell_centering.h
+++ b/alg/teca_face_to_cell_centering.h
@@ -10,10 +10,7 @@
 
 TECA_SHARED_OBJECT_FORWARD_DECL(teca_face_to_cell_centering)
 
-/// an algorithm that transforms vertical cooridinates
-/**
-An algorithm that transforms vertical coordinates of a mesh.
-*/
+/// An  algorithm that transforms from face to cell centering
 class teca_face_to_cell_centering : public teca_algorithm
 {
 public:
diff --git a/alg/teca_indexed_dataset_cache.h b/alg/teca_indexed_dataset_cache.h
index 96c909836..d7863c7d6 100644
--- a/alg/teca_indexed_dataset_cache.h
+++ b/alg/teca_indexed_dataset_cache.h
@@ -30,10 +30,14 @@ class teca_indexed_dataset_cache : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    // set/get the max number of datasets to cache.
+    /** @name max_cache_size
+     * Set the max number of datasets to cache.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(unsigned long, max_cache_size)
+    ///@}
 
-    // clear any cached data.
+    /// clear any cached data.
     void clear_cache();
 
 protected:
diff --git a/alg/teca_integrated_vapor_transport.h b/alg/teca_integrated_vapor_transport.h
index 00655130e..4ce7649a7 100644
--- a/alg/teca_integrated_vapor_transport.h
+++ b/alg/teca_integrated_vapor_transport.h
@@ -15,9 +15,11 @@ TECA_SHARED_OBJECT_FORWARD_DECL(teca_integrated_vapor_transport)
  * Compute integrated vapor transport (IVT) from wind vector and
  * specific humidity.
  *
+ * \f[
  * IVT = \frac{1}{g} \int_{p_{sfc}}^{p_{top}} \vec{v} q dp
+ * \f]
  *
- * where q is the specific humidity, and \vec{v} = (u, v) are the
+ * where q is the specific humidity, and \f$\vec{v} = (u, v)\f$ are the
  * longitudinal and latitudinal components of wind.
  *
  * This calculation is an instance of a vertical reduction where
@@ -31,35 +33,59 @@ class teca_integrated_vapor_transport : public teca_vertical_reduction
     TECA_ALGORITHM_CLASS_NAME(teca_integrated_vapor_transport)
     ~teca_integrated_vapor_transport();
 
-    // report/initialize to/from Boost program options
-    // objects.
+    /** @name program_options
+     * report/initialize to/from Boost program options objects.
+     */
+    ///@{
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
+    ///@}
 
-    // set the name of the varaiable that contains the longitudinal
-    // component of the wind vector ("ua")
+    /** @name wind_u_variable
+     * set the name of the varaiable that contains the longitudinal component
+     * of the wind vector ("ua")
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, wind_u_variable)
+    ///@}
 
-    // set the name of the varaiable that contains the latitudinal
-    // component of the wind vector ("va")
+    /** @name wind_v_variable
+     * set the name of the varaiable that contains the latitudinal component of
+     * the wind vector ("va")
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, wind_v_variable)
-
-    // set the name of the variable that contains the specific
-    // humidity ("hus")
-    TECA_ALGORITHM_PROPERTY(std::string,
-        specific_humidity_variable)
-
-    // set the name of the varaiable that contains the longitudinal
-    // component of the ivt vector ("ivt_u")
+    ///@}
+
+    /** @name specific_humidity_variable
+     * set the name of the variable that contains the specific humidity ("hus")
+     */
+    ///@{
+    TECA_ALGORITHM_PROPERTY(std::string, specific_humidity_variable)
+    ///@}
+
+    /** @name ivt_u_variable
+     * set the name of the varaiable that contains the longitudinal component
+     * of the ivt vector ("ivt_u")
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, ivt_u_variable)
+    ///@}
 
-    // set the name of the varaiable that contains the latitudinal
-    // component of the ivt vector ("ivt_v")
+    /** @name ivt_v_variable
+     * set the name of the varaiable that contains the latitudinal component of
+     * the ivt vector ("ivt_v")
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, ivt_v_variable)
+    ///@}
 
-    // set the _fillValue attribute for the output data.
-    // default 1.0e20
+    /** @name fill_value
+     * set the _fillValue attribute for the output data.  default 1.0e20
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(double, fill_value)
+    ///@}
 
 protected:
     teca_integrated_vapor_transport();
diff --git a/alg/teca_integrated_water_vapor.h b/alg/teca_integrated_water_vapor.h
index 263ff02a2..3070e6a49 100644
--- a/alg/teca_integrated_water_vapor.h
+++ b/alg/teca_integrated_water_vapor.h
@@ -14,7 +14,9 @@ TECA_SHARED_OBJECT_FORWARD_DECL(teca_integrated_water_vapor)
 /**
  * Compute integrated vaport transport (IWV) from the specific humidity.
  *
+ * \f[
  * IWV = \frac{1}{g} \int_{p_{sfc}}^{p_{top}} q dp
+ * \f]
  *
  * where q is the specific humidity.
  *
@@ -34,16 +36,14 @@ class teca_integrated_water_vapor : public teca_vertical_reduction
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    /** @anchor specific_humidity_variable
-     * @name specific_humidity_variable
+    /** @name specific_humidity_variable
      * set the name of the variable that contains the specific humidity ("hus")
      */
     ///@{
     TECA_ALGORITHM_PROPERTY(std::string, specific_humidity_variable)
     ///@}
 
-    /** @anchor iwv_variable
-     * @name iwv_variable
+    /** @name iwv_variable
      * set the name of the varaiable that contains the integrated water vapor
      * ("iwv").
      */
@@ -51,8 +51,7 @@ class teca_integrated_water_vapor : public teca_vertical_reduction
     TECA_ALGORITHM_PROPERTY(std::string, iwv_variable)
     ///@}
 
-    /** @anchor fill_value
-     * @name fill_value
+    /** @name fill_value
      * set the _fillValue attribute for the output data.  default 1.0e20
      */
     ///@{
diff --git a/alg/teca_l2_norm.h b/alg/teca_l2_norm.h
index 21def4b80..5a67eceb0 100644
--- a/alg/teca_l2_norm.h
+++ b/alg/teca_l2_norm.h
@@ -10,10 +10,7 @@
 
 TECA_SHARED_OBJECT_FORWARD_DECL(teca_l2_norm)
 
-/// an algorithm that computes L2 norm
-/**
-Compute L2 norm
-*/
+/// An algorithm that computes L2 norm
 class teca_l2_norm : public teca_algorithm
 {
 public:
@@ -27,15 +24,37 @@ class teca_l2_norm : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    // set the arrays that contain the vector components
-    // to compute norm from
+    /** @name component_0_variable
+     * Set the arrays that contain the vector components to compute the norm
+     * from.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, component_0_variable)
+    ///@}
+
+    /** @name component_1_variable
+     * Set the arrays that contain the vector components to compute the norm
+     * from.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, component_1_variable)
+    ///@}
+
+    /** @name component_2_variable
+     * Set the arrays that contain the vector components to compute the norm
+     * from.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, component_2_variable)
+    ///@}
 
-    // set the name of the array to store the result in.
-    // the default is "l2_norm"
+    /** @name l2_norm_variable
+     * set the name of the array to store the result in.  the default is
+     * "l2_norm"
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, l2_norm_variable)
+    ///@}
 
 protected:
     teca_l2_norm();
diff --git a/alg/teca_laplacian.h b/alg/teca_laplacian.h
index 247e00bd4..35e623d39 100644
--- a/alg/teca_laplacian.h
+++ b/alg/teca_laplacian.h
@@ -10,10 +10,7 @@
 
 TECA_SHARED_OBJECT_FORWARD_DECL(teca_laplacian)
 
-/// an algorithm that computes laplacian
-/**
-Compute laplacian from a vector field.
-*/
+/// An algorithm that computes the Laplacian from a vector field.
 class teca_laplacian : public teca_algorithm
 {
 public:
@@ -27,14 +24,29 @@ class teca_laplacian : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    // set the arrays that contain the vector components
-    // to compute laplacian from
+    /** @name component_0_variable
+     * Set the arrays that contain the vector components to compute laplacian
+     * from.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, component_0_variable)
+    ///@}
+
+    /** @name component_1_variable
+     * Set the arrays that contain the vector components to compute laplacian
+     * from.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, component_1_variable)
+    ///@}
 
-    // set the name of the array to store the result in.
-    // the default is "laplacian"
+    /** @name laplacian_variable
+     * Set the name of the array to store the result in.  the default is
+     * "laplacian".
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, laplacian_variable)
+    ///@}
 
 protected:
     teca_laplacian();
diff --git a/alg/teca_mask.h b/alg/teca_mask.h
index 6c7dcb84d..02b6072e8 100644
--- a/alg/teca_mask.h
+++ b/alg/teca_mask.h
@@ -1,6 +1,8 @@
 #ifndef teca_mask_h
 #define teca_mask_h
 
+/// @file
+
 #include "teca_shared_object.h"
 #include "teca_algorithm.h"
 #include "teca_metadata.h"
@@ -11,9 +13,8 @@
 TECA_SHARED_OBJECT_FORWARD_DECL(teca_mask)
 
 /// an algorithm that masks a range of values
-/**
-An algorithm to mask a range of values in an array. Values
-in the range are replaced with the mask value.
+/** An algorithm to mask a range of values in an array. Values
+ * in the range are replaced with the mask value.
 */
 class teca_mask : public teca_algorithm
 {
diff --git a/alg/teca_normalize_coordinates.h b/alg/teca_normalize_coordinates.h
index 24acc37a1..265a269ab 100644
--- a/alg/teca_normalize_coordinates.h
+++ b/alg/teca_normalize_coordinates.h
@@ -21,8 +21,8 @@ TECA_SHARED_OBJECT_FORWARD_DECL(teca_normalize_coordinates)
  * 2. the y-axis coordinate are in ascending order.
  *
  * These transformations are automatically applied and can be enabled or
- * disbaled as needed. The properties @ref enable_periodic_shift and
- * @ref enable_y_axis_ascending provide a way to enable/disable the transforms.
+ * disbaled as needed. The properties enable_periodic_shift and
+ * enable_y_axis_ascending provide a way to enable/disable the transforms.
  *
  * Subset requests are not implemented when the periodic shift is enabled. When
  * a request is made for data that crosses the periodic boundary, the request
@@ -44,8 +44,7 @@ class teca_normalize_coordinates : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    /** @anchor enable_periodic_shift_x
-     * @name enable_periodic_shift_x
+    /** @name enable_periodic_shift_x
      * If set, this  enables an automatic transformation of the x-axis
      * coordinates and data from [-180, 180] to [0, 360]. When enabled, the
      * transformation is applied if the lowest x coordinate is less than 0 and
@@ -55,8 +54,7 @@ class teca_normalize_coordinates : public teca_algorithm
     TECA_ALGORITHM_PROPERTY(int, enable_periodic_shift_x)
     ///@}
 
-    /** @anchor enable_y_axis_ascending
-     * @name enable_y_axis_ascending
+    /** @name enable_y_axis_ascending
      * If set, this enables an automatic transformation of the y-axis
      * coordinates and data from descending to ascending order. The
      * transformation is applied if the lowest y coordinate is greater than the
diff --git a/alg/teca_rename_variables.h b/alg/teca_rename_variables.h
index 1b49eb404..24ebb7103 100644
--- a/alg/teca_rename_variables.h
+++ b/alg/teca_rename_variables.h
@@ -10,7 +10,7 @@
 
 TECA_SHARED_OBJECT_FORWARD_DECL(teca_rename_variables)
 
-/// An algorithm that renames original_variable_names.
+/// An algorithm that renames variables.
 class teca_rename_variables : public teca_algorithm
 {
 public:
@@ -24,18 +24,16 @@ class teca_rename_variables : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    /** @anchor original_variable_names
-     * @name original_variable_names
+    /** @name original_variable_names
      * Set the list of variables to rename. For each variable to rename a new
-     * name must be specified at the same index in the @ref new_variable_names
+     * name must be specified at the same index in the new_variable_names
      * list. The two lists must be the same length.
      */
     ///@{
     TECA_ALGORITHM_VECTOR_PROPERTY(std::string, original_variable_name)
     ///@}
 
-    /** @anchor new_variable_names
-     * @name new_variable_names
+    /** @name new_variable_names
      * Set the names of the renamed variables. The new names are applied to the
      * list of variables to rename in the same order and the two lists must be
      * the same length.
diff --git a/alg/teca_simple_moving_average.h b/alg/teca_simple_moving_average.h
index 0c94540fb..5b2f82d63 100644
--- a/alg/teca_simple_moving_average.h
+++ b/alg/teca_simple_moving_average.h
@@ -29,17 +29,25 @@ class teca_simple_moving_average : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    // set the number of steps to average. should be odd.
+    /** @name filter_width
+     * set the number of steps to average. should be odd.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(unsigned int, filter_width)
+    ///@}
 
 
-    // select the filter stencil, default is backward
+    /** @name filter_type
+     * select the filter stencil, default is backward
+     */
+    ///@{
     enum {
         backward,
         centered,
         forward
     };
     TECA_ALGORITHM_PROPERTY(int, filter_type)
+    ///@}
 
 protected:
     teca_simple_moving_average();
diff --git a/alg/teca_table_reduce.h b/alg/teca_table_reduce.h
index 9bf0ecbe6..6add595c6 100644
--- a/alg/teca_table_reduce.h
+++ b/alg/teca_table_reduce.h
@@ -2,7 +2,7 @@
 #define teca_table_reduce_h
 
 #include "teca_shared_object.h"
-#include "teca_dataset_fwd.h"
+#include "teca_dataset.h"
 #include "teca_metadata.h"
 #include "teca_index_reduce.h"
 
diff --git a/alg/teca_table_remove_rows.h b/alg/teca_table_remove_rows.h
index 837b3e7fa..882f3b259 100644
--- a/alg/teca_table_remove_rows.h
+++ b/alg/teca_table_remove_rows.h
@@ -41,17 +41,27 @@ class teca_table_remove_rows : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    // set the expression to use to determine which rows
-    // are removed. rows are removed where the expression
-    // evaluates true.
+    /** @name mask_expression
+     * set the expression to use to determine which rows are removed. rows are
+     * removed where the expression evaluates true.
+     */
+    ///@{
+    /// Set the mask expression
     void set_mask_expression(const std::string &expr);
 
+    /// Get the mask expression
     std::string get_mask_expression()
     { return this->mask_expression; }
+    ///@}
 
-    // when set columns used in the calculation are removed
-    // from the output. default off.
+    /** @name remove_dependent_variables
+     * when set columns used in the calculation are removed from the output.
+     * default off.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(int, remove_dependent_variables)
+    ///@}
+
 
 protected:
     teca_table_remove_rows();
diff --git a/alg/teca_table_to_stream.h b/alg/teca_table_to_stream.h
index 69dc848b8..c88c6d747 100644
--- a/alg/teca_table_to_stream.h
+++ b/alg/teca_table_to_stream.h
@@ -11,10 +11,7 @@
 
 TECA_SHARED_OBJECT_FORWARD_DECL(teca_table_to_stream)
 
-/// An algorithm that serializes a table to a c++ stream object.
-/**
- * This is primarily useful for debugging.
- */
+/// An algorithm that serializes a table to a C++ stream object.
 class teca_table_to_stream : public teca_algorithm
 {
 public:
diff --git a/alg/teca_tc_classify.h b/alg/teca_tc_classify.h
index efec9e852..1f2ae884a 100644
--- a/alg/teca_tc_classify.h
+++ b/alg/teca_tc_classify.h
@@ -12,12 +12,12 @@ TECA_SHARED_OBJECT_FORWARD_DECL(teca_tc_classify)
 
 /// an algorithm that classifies storms using Saphire-Simpson scale
 /**
-An algorithm that classifies storms using Saphire-Simpson scale
-a column containing the classification is added to the output
-
-An algorithm that sorts the storms by geographic region
-and category. tyhe output is a table where regions is
-mapped to columns and category is mapped to rows.
+ * An algorithm that classifies storms using Saphire-Simpson scale a column
+ * containing the classification is added to the output
+ *
+ * An algorithm that sorts the storms by geographic region and category. tyhe
+ * output is a table where regions is mapped to columns and category is mapped to
+rows.
 */
 class teca_tc_classify : public teca_algorithm
 {
diff --git a/alg/teca_tc_trajectory.h b/alg/teca_tc_trajectory.h
index 2154cc881..26c487e6a 100644
--- a/alg/teca_tc_trajectory.h
+++ b/alg/teca_tc_trajectory.h
@@ -11,28 +11,25 @@
 TECA_SHARED_OBJECT_FORWARD_DECL(teca_tc_trajectory)
 
 /// GFDL tropical storms trajectory tracking algorithm
-/**
-GFDL tropical storms trajectory tracking algorithm
-
-for more information see
-"Seasonal forecasting of tropical storms using coupled GCM integrations"
-
-computes trajectories from table of detections. trajectories
-are stored in a table.
-
-the trajectory computation makes use of the following paramteters:
-
-max_daily_distance (1600 km)
-    event must be within this distance on the
-    following day to be considered as part of the trajectory.
-
-min_wind_speed (17 m/s)
-    850 mb wind sped must be above this value.
-
-min_wind_duration (2 days)
-    criteria must be satisfied for this many days to be
-    a candidate
-*/
+/** for more information see
+ * "Seasonal forecasting of tropical storms using coupled GCM integrations"
+ *
+ * computes trajectories from table of detections. trajectories
+ * are stored in a table.
+ *
+ * the trajectory computation makes use of the following paramteters:
+ *
+ * max_daily_distance (1600 km)
+ *     event must be within this distance on the
+ *     following day to be considered as part of the trajectory.
+ *
+ * min_wind_speed (17 m/s)
+ *     850 mb wind sped must be above this value.
+ *
+ * min_wind_duration (2 days)
+ *     criteria must be satisfied for this many days to be
+ *     a candidate
+ */
 class teca_tc_trajectory : public teca_algorithm
 {
 public:
diff --git a/alg/teca_tc_wind_radii.h b/alg/teca_tc_wind_radii.h
index 6b9befc38..d44b0282d 100644
--- a/alg/teca_tc_wind_radii.h
+++ b/alg/teca_tc_wind_radii.h
@@ -12,15 +12,14 @@ TECA_SHARED_OBJECT_FORWARD_DECL(teca_tc_wind_radii)
 
 /// computes wind radius at the specified coordinates
 /**
-Compute storm size and adds it to the table. There are two inputs,
-the first serves up tables of storms to compute the storm radius
-for. One must set the names of the columns that contain storm ids,
-x-coordnates, y-coordinates, and time coordinate. For each event
-the wind radius is computed. Computations are parallelized over
-storm id. The second input serves up wind velocity data most likely
-this will be from a NetCDF CF2 simulation dataset. By default
-radius is computed at the transitions on the Saffir-Simpson
-scale. 
+ * Compute storm size and adds it to the table. There are two inputs, the first
+ * serves up tables of storms to compute the storm radius for. One must set the
+ * names of the columns that contain storm ids, x-coordnates, y-coordinates,
+ * and time coordinate. For each event the wind radius is computed.
+ * Computations are parallelized over storm id. The second input serves up wind
+ * velocity data most likely this will be from a NetCDF CF2 simulation dataset.
+ * By default radius is computed at the transitions on the Saffir-Simpson
+ * scale.
 */
 class teca_tc_wind_radii : public teca_algorithm
 {
@@ -35,59 +34,110 @@ class teca_tc_wind_radii : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    // set the name of the column that defines the track ids
-    // if set the specified column is coppied into the output
-    // metadata and accessed with the key event_id
+    /** @name storm_id_column
+     * set the name of the column that defines the track ids if set the
+     * specified column is coppied into the output metadata and accessed with
+     * the key event_id
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, storm_id_column)
-
-    // set the name of the columns that define the event position
-    // if  set the columns are coppied into the output metadata
-    // and accessed with the keys storm_x_coordinate, storm_y_coordinate
+    ///@}
+
+    /** @name storm_x_coordinate_column
+     * set the name of the columns that define the event position if  set the
+     * columns are coppied into the output metadata and accessed with the keys
+     * storm_x_coordinate, storm_y_coordinate
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, storm_x_coordinate_column)
+    ///@}
+
+    /** @name storm_y_coordinate_column
+     * set the name of the columns that define the event position if  set the
+     * columns are coppied into the output metadata and accessed with the keys
+     * storm_x_coordinate, storm_y_coordinate
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, storm_y_coordinate_column)
+    ///@}
 
-    // set the name of the column containing peak instantanious
-    // surface wind speed
+    /** @name storm_wind_speed_column
+     * set the name of the column containing peak instantanious surface wind
+     * speed
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, storm_wind_speed_column)
-
-    // set the name of the column that defines the event time
-    // if set the specified column is coppied into the output
-    // metadata and accessed with the key event_time
+    ///@}
+
+    /** @name storm_time_column
+     * set the name of the column that defines the event time if set the
+     * specified column is coppied into the output metadata and accessed with
+     * the key event_time
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, storm_time_column)
+    ///@}
 
     // set the name of the wind variable components
+    /** @name wind_u_variable
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, wind_u_variable)
+    ///@}
+
+    /** @name wind_v_variable
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, wind_v_variable)
+    ///@}
 
-    // set the radius in degrees of latitude to sample the wind
-    // field
+    /** @name search_radius
+     * set the radius in degrees of latitude to sample the wind field
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(double, search_radius)
-
-    // set the radius in degrees of latitude beyond which to
-    // terminate the search for peak wind speed. if the peak
-    // lies beyond this distance search is terminated and a
-    // warning is displayed.
+    ///@}
+
+    /** @name core_radius
+     * set the radius in degrees of latitude beyond which to terminate the
+     * search for peak wind speed. if the peak lies beyond this distance search
+     * is terminated and a warning is displayed.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(double, core_radius)
+    ///@}
 
-    // number of bins to discetize by in the radial direction
+    /** @name number_of_radial_bins
+     * number of bins to discetize by in the radial direction
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(int, number_of_radial_bins)
+    ///@}
 
-    // set the wind speeds (in m/s) to find the radius of. the
-    // defualt values are the transition speeds of the Saffir-Simpson
-    // scale.
+    /** @name critical_wind_speed
+     * set the wind speeds (in m/s) to find the radius of. the defualt values
+     * are the transition speeds of the Saffir-Simpson scale.
+     */
+    ///@{
     TECA_ALGORITHM_VECTOR_PROPERTY(double, critical_wind_speed)
-
-    // set the profile type. PROFILE_MAX uses the maximum
-    // wind speed on each interval of the discretization, while
-    // PROFILE_AVERAGE uses the average on each interval
+    ///@}
+
+    /** @name profile_type
+     * Set the profile type. PROFILE_MAX uses the maximum wind speed on each
+     * interval of the discretization, while PROFILE_AVERAGE uses the average
+     * on each interval
+     */
+    ///@{
+    /// Profile types
     enum {PROFILE_MAX = 0, PROFILE_AVERAGE = 1};
-    TECA_ALGORITHM_PROPERTY(int, profile_type);
 
+    TECA_ALGORITHM_PROPERTY(int, profile_type)
+    ///@}
 
-    // override the input connections because we are going to
-    // take the first input and use it to generate metadata.
-    // the second input then becomes the only one the pipeline
-    // knows about.
+    /** override the input connections because we are going to take the first
+     * input and use it to generate metadata.  the second input then becomes
+     * the only one the pipeline knows about.
+     */
     void set_input_connection(unsigned int id,
         const teca_algorithm_output_port &port) override;
 
diff --git a/alg/teca_unpack_data.h b/alg/teca_unpack_data.h
index 33d01db6e..373535f2a 100644
--- a/alg/teca_unpack_data.h
+++ b/alg/teca_unpack_data.h
@@ -13,19 +13,19 @@ TECA_SHARED_OBJECT_FORWARD_DECL(teca_unpack_data)
 
 /// an algorithm that unpacks NetCDF packed values
 /**
-Applies a data transform according to the NetCDF attribute conventions for
-packed data values.
-https://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html
-
-Variables in the input dataset are scanned for the presence
-of the `scale_factor` and `add_offset` attributes. When both are present
-an element wise transformation is applied such that
-
-out[i] = scale_factor * in[i] + add_offset
-
-The input array is expected to be an integer type while the type of the output
-array may be either float or double. Valid value masks may be necessary for
-correct results, see `teca_valid_value_mask`.
+ * Applies a data transform according to the NetCDF attribute conventions for
+ * packed data values.
+ * https://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html
+ *
+ * Variables in the input dataset are scanned for the presence
+ * of the `scale_factor` and `add_offset` attributes. When both are present
+ * an element wise transformation is applied such that
+ *
+ * out[i] = scale_factor * in[i] + add_offset
+ *
+ * The input array is expected to be an integer type while the type of the output
+ * array may be either float or double. Valid value masks may be necessary for
+ * correct results, see `teca_valid_value_mask`.
 */
 class teca_unpack_data : public teca_algorithm
 {
@@ -40,19 +40,22 @@ class teca_unpack_data : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    // set the output data type.
-    // use teca_variant_array_code<T>::get() to get the numeric
-    // code corresponding to the data type T. The default output
-    // data type is single precision floating point.
+    /** @name output_data_type
+     * set the output data type.  use teca_variant_array_code<T>::get() to get
+     * the numeric code corresponding to the data type T. The default output
+     * data type is single precision floating point.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY_V(int, output_data_type)
 
-    // set the output data type to double precision floating point
+    /// set the output data type to double precision floating point
     void set_output_data_type_to_float()
     { this->set_output_data_type(teca_variant_array_code<float>::get()); }
 
-    // set the output data type to single precision floating point
+    /// set the output data type to single precision floating point
     void set_output_data_type_to_double()
     { this->set_output_data_type(teca_variant_array_code<double>::get()); }
+    ///@}
 
 protected:
     teca_unpack_data();
diff --git a/alg/teca_valid_value_mask.h b/alg/teca_valid_value_mask.h
index a0176f402..dfa90b9a3 100644
--- a/alg/teca_valid_value_mask.h
+++ b/alg/teca_valid_value_mask.h
@@ -27,7 +27,7 @@ TECA_SHARED_OBJECT_FORWARD_DECL(teca_valid_value_mask)
  * a variable named "V" it will be named "V_valid".
  *
  * Masks are requested for specific arrays in one of two ways. One may use the
- * @ref mask_arrays algorithm property to explicitly name the list of variables to
+ * mask_arrays algorithm property to explicitly name the list of variables to
  * compute masks for. Alternatively, a heuristic applied to incoming requests
  * determines if masks should be generated. Specifically the string "_valid" is
  * looked for at the end of each requested array.  If it is found then the mask
@@ -48,8 +48,7 @@ class teca_valid_value_mask : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    /** @anchor mask_arrays
-     * @name mask_arrays
+    /** @name mask_arrays
      * explicitly set a list of input arrays to process. By default
      * all arrays are processed. Use this property to compute masks
      * for a subset of the arrays,
@@ -58,8 +57,7 @@ class teca_valid_value_mask : public teca_algorithm
     TECA_ALGORITHM_VECTOR_PROPERTY(std::string, mask_array)
     ///@}
 
-    /** @anchor enable_valid_range
-     * @name enable_valid_range
+    /** @name enable_valid_range
      * enable the use of valid_range, valid_min, valid_max attributes.
      * by default this is off.
      */
diff --git a/alg/teca_vertical_coordinate_transform.h b/alg/teca_vertical_coordinate_transform.h
index 1e3b27ba1..da5073bfb 100644
--- a/alg/teca_vertical_coordinate_transform.h
+++ b/alg/teca_vertical_coordinate_transform.h
@@ -10,10 +10,7 @@
 
 TECA_SHARED_OBJECT_FORWARD_DECL(teca_vertical_coordinate_transform)
 
-/// an algorithm that transforms vertical cooridinates
-/**
-An algorithm that transforms vertical coordinates of a mesh.
-*/
+/// An algorithm that transforms the vertical cooridinates of a mesh
 class teca_vertical_coordinate_transform : public teca_algorithm
 {
 public:
diff --git a/alg/teca_vertical_reduction.h b/alg/teca_vertical_reduction.h
index a47362408..bbeb72487 100644
--- a/alg/teca_vertical_reduction.h
+++ b/alg/teca_vertical_reduction.h
@@ -11,11 +11,11 @@
 
 TECA_SHARED_OBJECT_FORWARD_DECL(teca_vertical_reduction)
 
-/// base class for vertical reducitons
+/// The base class for vertical reducitons.
 /**
-implements common operations associated with computing a vertical
-reduction where a 3D dataset is transformed into a 2D dataset
-by a reduction along the 3rd spatial dimension.
+ * implements common operations associated with computing a vertical
+ * reduction where a 3D dataset is transformed into a 2D dataset
+ * by a reduction along the 3rd spatial dimension.
 */
 class teca_vertical_reduction : public teca_algorithm
 {
@@ -30,16 +30,27 @@ class teca_vertical_reduction : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    // set/get the list of variables that are needed to produce
-    // the derived quantity
+    /** @name dependent_variable
+     * set/get the list of variables that are needed to produce the derived
+     * quantity
+     */
+    ///@{
     TECA_ALGORITHM_VECTOR_PROPERTY(std::string, dependent_variable)
+    ///@}
 
-    // set/get the name of the variable that is produced
+    /** @name derived_variable
+     * set/get the name of the variable that is produced
+     */
+    ///@{
     TECA_ALGORITHM_VECTOR_PROPERTY(std::string, derived_variable)
+    ///@}
 
-    // set/get the attributes of the variable that is produced
-    TECA_ALGORITHM_VECTOR_PROPERTY(teca_array_attributes,
-        derived_variable_attribute)
+    /** @name derived_variable_attribute
+     * Set the attributes of the variable that is produced.
+     */
+    ///@{
+    TECA_ALGORITHM_VECTOR_PROPERTY(teca_array_attributes, derived_variable_attribute)
+    ///@}
 
 protected:
     teca_vertical_reduction();
diff --git a/alg/teca_vorticity.h b/alg/teca_vorticity.h
index 7ac3226f6..b42cd0d6c 100644
--- a/alg/teca_vorticity.h
+++ b/alg/teca_vorticity.h
@@ -10,10 +10,7 @@
 
 TECA_SHARED_OBJECT_FORWARD_DECL(teca_vorticity)
 
-/// an algorithm that computes vorticity
-/**
-Compute vorticity from a vector field.
-*/
+/// An algorithm that computes vorticity from a vector field.
 class teca_vorticity : public teca_algorithm
 {
 public:
@@ -27,14 +24,29 @@ class teca_vorticity : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    // set the arrays that contain the vector components
-    // to compute vorticity from
+    /** @name component_0_variable
+     * set the arrays that contain the vector components to compute vorticity
+     * from.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, component_0_variable)
+    ///@}
+
+    /** @name component_1_variable
+     * set the arrays that contain the vector components to compute vorticity
+     * from.
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, component_1_variable)
+    ///@}
 
-    // set the name of the array to store the result in.
-    // the default is "vorticity"
+    /** @name vorticity_variable
+     * set the name of the array to store the result in.  the default is
+     * "vorticity"
+     */
+    ///@{
     TECA_ALGORITHM_PROPERTY(std::string, vorticity_variable)
+    ///@}
 
 protected:
     teca_vorticity();
diff --git a/core/teca_algorithm.h b/core/teca_algorithm.h
index 86e228638..4fd2dc709 100644
--- a/core/teca_algorithm.h
+++ b/core/teca_algorithm.h
@@ -2,24 +2,235 @@
 #define teca_algorithm_h
 
 #include "teca_config.h"
-
-// forward declaration of ref counted types
-#include "teca_dataset_fwd.h"
-#include "teca_algorithm_fwd.h"
-#include "teca_algorithm_executive_fwd.h"
-class teca_algorithm_internals;
-
-// for types used in the API
+#include "teca_shared_object.h"
+#include "teca_dataset.h"
+#include "teca_algorithm_executive.h"
 #include "teca_metadata.h"
-#include "teca_algorithm_output_port.h"
 #include "teca_program_options.h"
 #include "teca_mpi.h"
 
 #include <vector>
 #include <utility>
 #include <iosfwd>
+#include <initializer_list>
+#include <functional>
+
+class teca_algorithm_internals;
+
+TECA_SHARED_OBJECT_FORWARD_DECL(teca_algorithm)
+
+/// An output port packages an algorithm and a port number
+using teca_algorithm_output_port
+    = std::pair<p_teca_algorithm, unsigned int>;
+
+/// get the algorithm from the output port
+inline
+p_teca_algorithm &get_algorithm(teca_algorithm_output_port &op)
+{ return op.first; }
+
+/// get port number from the output port
+inline
+unsigned int &get_port(teca_algorithm_output_port &op)
+{ return op.second; }
+
+/* this is a convenience macro to be used to declare a static New method that
+ * will be used to construct new objects in shared_ptr's. This manages the
+ * details of interoperability with std C++11 shared pointer
+ */
+#define TECA_ALGORITHM_STATIC_NEW(T)                \
+                                                    \
+/** Returns an instance of T */                     \
+static p_##T New()                                  \
+{                                                   \
+    return p_##T(new T);                            \
+}                                                   \
+                                                    \
+/** Enables the static constructor */               \
+std::shared_ptr<T> shared_from_this()               \
+{                                                   \
+    return std::static_pointer_cast<T>(             \
+        teca_algorithm::shared_from_this());        \
+}                                                   \
+                                                    \
+/** Enables the static constructor */               \
+std::shared_ptr<T const> shared_from_this() const   \
+{                                                   \
+    return std::static_pointer_cast<T const>(       \
+        teca_algorithm::shared_from_this());        \
+}
+
+#define TECA_ALGORITHM_CLASS_NAME(T)                \
+/** returns the name of the class */                \
+const char *get_class_name() const override         \
+{                                                   \
+    return #T;                                      \
+}
+
+/** this convenience macro removes copy and assignment operators
+ * which generally should not be defined for reference counted types
+ */
+#define TECA_ALGORITHM_DELETE_COPY_ASSIGN(T)    \
+                                                \
+    T(const T &src) = delete;                   \
+    T(T &&src) = delete;                        \
+                                                \
+    T &operator=(const T &src) = delete;        \
+    T &operator=(T &&src) = delete;
+
+/** convenience macro to declare standard set_NAME/get_NAME methods
+ * where NAME is the name of a class member. will manage the
+ * algorithm's modified state for the user.
+ */
+#define TECA_ALGORITHM_PROPERTY(T, NAME)                 \
+                                                         \
+/** Set the value of the NAME algorithm property */      \
+void set_##NAME(const T &v)                              \
+{                                                        \
+    if (this->NAME != v)                                 \
+    {                                                    \
+        this->NAME = v;                                  \
+        this->set_modified();                            \
+    }                                                    \
+}                                                        \
+                                                         \
+/** Get the value of the NAME algorithm property */      \
+const T &get_##NAME() const                              \
+{                                                        \
+    return this->NAME;                                   \
+}
+
+/** similar to TECA_ALGORITHM_PROPERTY but prior to setting NAME
+ * will call the member function int valididate_NAME(T v). If
+ * the value v is valid the fucntion should return 0. If the value
+ * is not zero the function should invoke TECA_ERROR with a
+ * descriptive message and return non-zero.
+ */
+#define TECA_ALGORITHM_PROPERTY_V(T, NAME)               \
+                                                         \
+/** Set the value of the NAME algorithm property */      \
+void set_##NAME(const T &v)                              \
+{                                                        \
+    if (this->validate_ ## NAME (v))                     \
+        return;                                          \
+                                                         \
+    if (this->NAME != v)                                 \
+    {                                                    \
+        this->NAME = v;                                  \
+        this->set_modified();                            \
+    }                                                    \
+}                                                        \
+                                                         \
+/** Get the value of the NAME algorithm property */      \
+const T &get_##NAME() const                              \
+{                                                        \
+    return this->NAME;                                   \
+}
+
+/** convenience macro to declare standard set_NAME/get_NAME methods
+ * where NAME is the name of a class member. will manage the
+ * algorithm's modified state for the user.
+ */
+#define TECA_ALGORITHM_VECTOR_PROPERTY(T, NAME)                           \
+                                                                          \
+/** get the size of the NAME algorithm vector property */                 \
+size_t get_number_of_##NAME##s ()                                         \
+{                                                                         \
+    return this->NAME##s.size();                                          \
+}                                                                         \
+                                                                          \
+/** append to the NAME algorithm vector property */                       \
+void append_##NAME(const T &v)                                            \
+{                                                                         \
+    this->NAME##s.push_back(v);                                           \
+    this->set_modified();                                                 \
+}                                                                         \
+                                                                          \
+/** set the i-th element of the NAME algorithm vector property */         \
+void set_##NAME(size_t i, const T &v)                                     \
+{                                                                         \
+    if (this->NAME##s[i] != v)                                            \
+    {                                                                     \
+        this->NAME##s[i] = v;                                             \
+        this->set_modified();                                             \
+    }                                                                     \
+}                                                                         \
+                                                                          \
+/** set the  NAME algorithm vector property */                            \
+void set_##NAME##s(const std::vector<T> &v)                               \
+{                                                                         \
+    if (this->NAME##s != v)                                               \
+    {                                                                     \
+        this->NAME##s = v;                                                \
+        this->set_modified();                                             \
+    }                                                                     \
+}                                                                         \
+                                                                          \
+/** set the  NAME algorithm vector property */                            \
+void set_##NAME##s(const std::initializer_list<T> &&l)                    \
+{                                                                         \
+    std::vector<T> v(l);                                                  \
+    if (this->NAME##s != v)                                               \
+    {                                                                     \
+        this->NAME##s = v;                                                \
+        this->set_modified();                                             \
+    }                                                                     \
+}                                                                         \
+                                                                          \
+/** get the i-th element of the NAME algorithm vector property */         \
+const T &get_##NAME(size_t i) const                                       \
+{                                                                         \
+    return this->NAME##s[i];                                              \
+}                                                                         \
+                                                                          \
+/** get the  NAME algorithm vector property */                            \
+const std::vector<T> &get_##NAME##s() const                               \
+{                                                                         \
+    return this->NAME##s;                                                 \
+}                                                                         \
+                                                                          \
+/** clear the  NAME algorithm vector property */                          \
+void clear_##NAME##s()                                                    \
+{                                                                         \
+    this->NAME##s.clear();                                                \
+}
+
+/// helper that allows us to use std::function as a TECA_ALGORITHM_PROPERTY
+template<typename T>
+bool operator!=(const std::function<T> &lhs, const std::function<T> &rhs)
+{
+    return &rhs != &lhs;
+}
 
-/// Interface to TECA pipeline architecture.
+/** This is a work around for older versions of Apple clang
+ * Apple LLVM version 4.2 (clang-425.0.28) (based on LLVM 3.2svn)
+ * Target: x86_64-apple-darwin12.6.0
+ */
+#define TECA_ALGORITHM_CALLBACK_PROPERTY(T, NAME)   \
+                                                    \
+/** Set the NAME algorithm property */              \
+void set_##NAME(const T &v)                         \
+{                                                   \
+    /*if (this->NAME != v)*/                        \
+    /*{*/                                           \
+        this->NAME = v;                             \
+        this->set_modified();                       \
+    /*}*/                                           \
+}                                                   \
+                                                    \
+/** Get the NAME algorithm property */              \
+const T &get_##NAME() const                         \
+{                                                   \
+    return this->NAME;                              \
+}                                                   \
+                                                    \
+/** Get the NAME algorithm property */              \
+T &get_##NAME()                                     \
+{                                                   \
+    return this->NAME;                              \
+}
+
+
+/// The interface to TECA pipeline architecture.
 /**
  * All sources/readers filters, sinks/writers will implement this interface.
  */
@@ -31,36 +242,40 @@ class teca_algorithm : public std::enable_shared_from_this<teca_algorithm>
 
     TECA_ALGORITHM_DELETE_COPY_ASSIGN(teca_algorithm)
 
-    // return the name of the class.
+    /// return the name of the class.
     virtual const char *get_class_name() const = 0;
 
-    // set/get the communicator to use at this stage of the pipeline this has
-    // no influence on other stages. We duplicate the passed in communicator
-    // providing an isolated communication space for subsequent operations. By
-    // default the communicator is initialized to MPI_COMM_WORLD, here it is not
-    // duplicated. Thus to put an algorithm into a unique communication space
-    // one should explicitly set a communicator. When an algorithm should not
-    // use MPI, for instance when it is in a nested pipeline, one may set the
-    // communicator to MPI_COMM_SELF.
+    /** set the communicator to use at this stage of the pipeline this has
+     * no influence on other stages. We duplicate the passed in communicator
+     * providing an isolated communication space for subsequent operations. By
+     * default the communicator is initialized to MPI_COMM_WORLD, here it is not
+     * duplicated. Thus to put an algorithm into a unique communication space
+     * one should explicitly set a communicator. When an algorithm should not
+     * use MPI, for instance when it is in a nested pipeline, one may set the
+     * communicator to MPI_COMM_SELF.
+     */
     void set_communicator(MPI_Comm comm);
+
+    /// get the active communicator
     MPI_Comm get_communicator();
 
 #if defined(TECA_HAS_BOOST)
-    // initialize the given options description with algorithm's properties
-    // implementors should call the base implementation when overriding.
-    // this should be called after the override adds its options.
+    /** initialize the given options description with algorithm's properties
+     * implementors should call the base implementation when overriding.
+     * this should be called after the override adds its options.
+     */
     virtual void get_properties_description(const std::string &prefix,
         options_description &opts);
 
-    // initialize the algorithm from the given options variable map.
-    // implementors should call the base implementation when overriding.
-    // this should be called before the override sets its properties.
+    /** initialize the algorithm from the given options variable map.
+     * implementors should call the base implementation when overriding.
+     * this should be called before the override sets its properties.
+     */
     virtual void set_properties(const std::string &prefix,
         variables_map &opts);
 #endif
 
-    /** @anchor verbose
-     * @name verbose
+    /** @name verbose
      * if set to a non-zero value, rank 0 will send status information to the
      * terminal. The default setting of zero results in no output.
      */
@@ -68,72 +283,90 @@ class teca_algorithm : public std::enable_shared_from_this<teca_algorithm>
     TECA_ALGORITHM_PROPERTY(int, verbose)
     ///@}
 
-    // get an output port from the algorithm. to be used
-    // during pipeline building
+    /** get an output port from the algorithm. to be used during pipeline
+     * building
+     */
     virtual
     teca_algorithm_output_port get_output_port(unsigned int port = 0);
 
-    // set an input to this algorithm
+    /// set an input to this algorithm
     void set_input_connection(const teca_algorithm_output_port &port)
     { this->set_input_connection(0, port); }
 
+    /// set an input to this algorithm
     virtual
     void set_input_connection(unsigned int id,
         const teca_algorithm_output_port &port);
 
-    // remove input connections
+    /// remove input connections
     virtual
     void remove_input_connection(unsigned int id);
 
-    // remove all input connections
+    /// remove all input connections
     void clear_input_connections();
 
-    // access the cached data produced by this algorithm. when no
-    // request is specified the dataset on the top(most recent) of
-    // the cache is returned. When a request is specified it may
-    // optionally be filtered by the implementations cache key filter.
-    // see also get_cache_key (threadsafe)
+    /** access the cached data produced by this algorithm. when no request is
+     * specified the dataset on the top(most recent) of the cache is returned.
+     * When a request is specified it may optionally be filtered by the
+     * implementations cache key filter.  see also get_cache_key (threadsafe)
+     */
     const_p_teca_dataset get_output_data(unsigned int port = 0);
 
-    // remove a dataset from the top/bottom of the cache. the
-    // top of the cache has the most recently created dataset.
-    // top or bottom is selected via the boolean argument.
-    // (threadsafe)
+    /** remove a dataset from the top/bottom of the cache. the top of the cache
+     * has the most recently created dataset.  top or bottom is selected via
+     * the boolean argument.  (threadsafe)
+     */
     void pop_cache(unsigned int port = 0, int top = 0);
 
-    // set the cache size. the default is 1. (threadsafe)
+    /// set the cache size. the default is 1. (threadsafe)
     void set_cache_size(unsigned int n);
 
-    // execute the pipeline from this instance up.
+    /// execute the pipeline from this instance up.
     virtual int update();
+
+    /// execute the pipeline from this instance up.
     virtual int update(unsigned int port);
 
-    // get meta data considering this instance up.
+    /// get meta data considering this instance up.
     virtual teca_metadata update_metadata(unsigned int port = 0);
 
-    // set the executive
+    /// set the executive
     void set_executive(p_teca_algorithm_executive exe);
+
+    /// get the executive
     p_teca_algorithm_executive get_executive();
 
-    // serialize the configuration to a stream. this should
-    // store the public user modifiable properties so that
-    // runtime configuration may be saved and restored..
+    /** serialize the configuration to a stream. this should store the public
+     * user modifiable properties so that runtime configuration may be saved
+     * and restored.
+     */
     virtual void to_stream(std::ostream &s) const;
+
+    /// deserialize from the stream.
     virtual void from_stream(std::istream &s);
 
 protected:
     teca_algorithm();
 
-    // implementations should call this from their constructors
-    // to setup the internal caches and data structures required
-    // for execution.
+    /** Set the number of input connections. implementations should call this
+     * from their constructors to setup the internal caches and data structures
+     * required for execution.
+     */
     void set_number_of_input_connections(unsigned int n);
+
+    /** Set the number of output ports. implementations should call this from
+     * their constructors to setup the internal caches and data structures
+     * required for execution.
+     */
     void set_number_of_output_ports(unsigned int n);
 
-    // set the modified flag on the given output port's cache.
-    // should be called when user modifies properties on the
-    // object that require the output to be regenerated.
+    /** set the modified flag on the given output port's cache.  should be
+     * called when user modifies properties on the object that require the
+     * output to be regenerated.
+     */
     virtual void set_modified();
+
+    /// an overload to set_modified by port
     void set_modified(unsigned int port);
 
 protected:
@@ -142,46 +375,43 @@ class teca_algorithm : public std::enable_shared_from_this<teca_algorithm>
 // teca_algorithm's such as reader, filters, and
 // writers.
 
-    // implementations must override this method to provide
-    // information to downstream consumers about what data
-    // will be produced on each output port. The port to
-    // provide information about is named in the first argument
-    // the second argument contains a list of the metadata
-    // describing data on all of the inputs.
+    /** implementations must override this method to provide information to
+     * downstream consumers about what data will be produced on each output
+     * port. The port to provide information about is named in the first
+     * argument the second argument contains a list of the metadata describing
+     * data on all of the inputs.
+     */
     virtual
     teca_metadata get_output_metadata(unsigned int port,
         const std::vector<teca_metadata> &input_md);
 
-    // implementations must override this method and
-    // generate a set of requests describing the data
-    // required on the inputs to produce data for the
-    // named output port, given the upstream meta data
-    // and request. If no data is needed on an input
-    // then the list should contain a null request.
+    /** implementations must override this method and generate a set of
+     * requests describing the data required on the inputs to produce data for
+     * the named output port, given the upstream meta data and request. If no
+     * data is needed on an input then the list should contain a null request.
+     */
     virtual
     std::vector<teca_metadata> get_upstream_request(
         unsigned int port, const std::vector<teca_metadata> &input_md,
         const teca_metadata &request);
 
-    // implementations must override this method and
-    // produce the output dataset for the port named
-    // in the first argument. The second argument is
-    // a list of all of the input datasets. See also
-    // get_request. The third argument contains a request
-    // from the consumer which can specify information
-    // such as arrays, subset region, timestep etc.
-    // The implementation is free to handle the request
-    // as it sees fit.
+    /** implementations must override this method and produce the output dataset
+     * for the port named in the first argument. The second argument is a list
+     * of all of the input datasets. See also get_request. The third argument
+     * contains a request from the consumer which can specify information such
+     * as arrays, subset region, timestep etc.  The implementation is free to
+     * handle the request as it sees fit.
+     */
     virtual
     const_p_teca_dataset execute(unsigned int port,
         const std::vector<const_p_teca_dataset> &input_data,
         const teca_metadata &request);
 
-    // implementations may choose to override this method
-    // to gain control of keys used in the cache. By default
-    // the passed in request is used as the key. This override
-    // gives implementor the chance to filter the passed in
-    // request.
+    /** implementations may choose to override this method to gain control of
+     * keys used in the cache. By default the passed in request is used as the
+     * key. This override gives implementor the chance to filter the passed in
+     * request.
+     */
     virtual
     teca_metadata get_cache_key(unsigned int port,
         const teca_metadata &request) const;
@@ -192,61 +422,66 @@ class teca_algorithm : public std::enable_shared_from_this<teca_algorithm>
 // need to be overridden when designing a new class
 // of algorithms.
 
-    // driver function that manage meta data reporting  phase
-    // of pipeline execution.
+    /** driver function that manage meta data reporting  phase of pipeline
+     * execution.
+     */
     virtual
     teca_metadata get_output_metadata(
         teca_algorithm_output_port &current);
 
-    // driver function that manages execution of the given
-    // request on the named port
+    /* driver function that manages execution of the given request on the named
+     * port
+     */
     virtual
     const_p_teca_dataset request_data(
         teca_algorithm_output_port &port,
         const teca_metadata &request);
 
-    // driver function that clears the output data cache
-    // where modified flag has been set from the current
-    // port upstream.
+    /** driver function that clears the output data cache where modified flag
+     * has been set from the current port upstream.
+     */
     virtual
     int validate_cache(teca_algorithm_output_port &current);
 
-    // driver function that clears the modified flag on the
-    // named port and all of it's upstream connections.
+    /** driver function that clears the modified flag on the named port and all
+     * of it's upstream connections.
+     */
     virtual
     void clear_modified(teca_algorithm_output_port current);
 
 protected:
 // api exposing internals for use in driver methods
 
-    // search the given port's cache for the dataset associated
-    // with the given request. see also get_cache_key. (threadsafe)
+    /** search the given port's cache for the dataset associated
+     * with the given request. see also get_cache_key. (threadsafe)
+     */
     const_p_teca_dataset get_output_data(unsigned int port,
         const teca_metadata &request);
 
-    // add or update the given request , dataset pair in the cache.
-    // see also get_cache_key. (threadsafe)
+    /** add or update the given request , dataset pair in the cache.  see also
+     * get_cache_key. (threadsafe)
+     */
     int cache_output_data(unsigned int port,
         const teca_metadata &request, const_p_teca_dataset &data);
 
-    // clear the cache on the given output port
+    /// clear the cache on the given output port
     void clear_cache(unsigned int port);
 
-    // get the number of input connections
+    /// get the number of input connections
     unsigned int get_number_of_input_connections();
 
-    // get the output port associated with this algorithm's
-    // i'th input connection.
+    /** get the output port associated with this algorithm's i'th input
+     * connection.
+     */
     teca_algorithm_output_port &get_input_connection(unsigned int i);
 
-    // clear the modified flag on the i'th output
+    /// clear the modified flag on the i'th output
     void clear_modified(unsigned int port);
 
-    // return the output port's modified flag value
+    /// return the output port's modified flag value
     int get_modified(unsigned int port) const;
 
 protected:
-// algorithm properties
     int verbose;
 
 private:
diff --git a/core/teca_algorithm_executive.h b/core/teca_algorithm_executive.h
index 52f22c702..239480438 100644
--- a/core/teca_algorithm_executive.h
+++ b/core/teca_algorithm_executive.h
@@ -1,9 +1,39 @@
 #ifndef teca_algorithm_executive_h
 #define teca_algorithm_executive_h
 
-#include "teca_algorithm_executive_fwd.h"
 #include "teca_metadata.h"
 #include "teca_mpi.h"
+#include "teca_shared_object.h"
+
+TECA_SHARED_OBJECT_FORWARD_DECL(teca_algorithm_executive)
+
+/* this is a convenience macro to be used to declare a static
+ * New method that will be used to construct new objects in
+ * shared_ptr's. This manages the details of interoperability
+ * with std C++11 shared pointer
+ */
+#define TECA_ALGORITHM_EXECUTIVE_STATIC_NEW(T)                      \
+                                                                    \
+                                                                    \
+/** Allocate a new T */                                             \
+static p_##T New()                                                  \
+{                                                                   \
+    return p_##T(new T);                                            \
+}                                                                   \
+                                                                    \
+std::shared_ptr<T> shared_from_this()                               \
+{                                                                   \
+    return std::static_pointer_cast<T>(                             \
+        teca_algorithm_executive::shared_from_this());              \
+}                                                                   \
+                                                                    \
+std::shared_ptr<T const> shared_from_this() const                   \
+{                                                                   \
+    return std::static_pointer_cast<T const>(                       \
+        teca_algorithm_executive::shared_from_this());              \
+}
+
+
 
 /// Base class and default implementation for executives.
 /**
diff --git a/core/teca_algorithm_executive_fwd.h b/core/teca_algorithm_executive_fwd.h
deleted file mode 100644
index 599cab2b5..000000000
--- a/core/teca_algorithm_executive_fwd.h
+++ /dev/null
@@ -1,31 +0,0 @@
-#ifndef teca_algorithm_executive_fwd_h
-#define teca_algorithm_executive_fwd_h
-
-#include "teca_shared_object.h"
-
-TECA_SHARED_OBJECT_FORWARD_DECL(teca_algorithm_executive)
-
-// this is a convenience macro to be used to declare a static
-// New method that will be used to construct new objects in
-// shared_ptr's. This manages the details of interoperability
-// with std C++11 shared pointer
-#define TECA_ALGORITHM_EXECUTIVE_STATIC_NEW(T)                      \
-                                                                    \
-static p_##T New()                                                  \
-{                                                                   \
-    return p_##T(new T);                                            \
-}                                                                   \
-                                                                    \
-std::shared_ptr<T> shared_from_this()                               \
-{                                                                   \
-    return std::static_pointer_cast<T>(                             \
-        teca_algorithm_executive::shared_from_this());              \
-}                                                                   \
-                                                                    \
-std::shared_ptr<T const> shared_from_this() const                   \
-{                                                                   \
-    return std::static_pointer_cast<T const>(                       \
-        teca_algorithm_executive::shared_from_this());              \
-}
-
-#endif
diff --git a/core/teca_algorithm_fwd.h b/core/teca_algorithm_fwd.h
deleted file mode 100644
index 67117bcca..000000000
--- a/core/teca_algorithm_fwd.h
+++ /dev/null
@@ -1,197 +0,0 @@
-#ifndef teca_algorithm_fwd_h
-#define teca_algorithm_fwd_h
-
-#include "teca_shared_object.h"
-
-#include <initializer_list>
-#include <functional>
-
-TECA_SHARED_OBJECT_FORWARD_DECL(teca_algorithm)
-
-// this is a convenience macro to be used to declare a static
-// New method that will be used to construct new objects in
-// shared_ptr's. This manages the details of interoperability
-// with std C++11 shared pointer
-#define TECA_ALGORITHM_STATIC_NEW(T)                \
-                                                    \
-static p_##T New()                                  \
-{                                                   \
-    return p_##T(new T);                            \
-}                                                   \
-                                                    \
-std::shared_ptr<T> shared_from_this()               \
-{                                                   \
-    return std::static_pointer_cast<T>(             \
-        teca_algorithm::shared_from_this());        \
-}                                                   \
-                                                    \
-std::shared_ptr<T const> shared_from_this() const   \
-{                                                   \
-    return std::static_pointer_cast<T const>(       \
-        teca_algorithm::shared_from_this());        \
-}
-
-#define TECA_ALGORITHM_CLASS_NAME(T)                \
-/** returns the name of the class */                \
-const char *get_class_name() const override         \
-{                                                   \
-    return #T;                                      \
-}
-
-// this convenience macro removes copy and aassignment operators
-// which generally should not be defined for reference counted types
-#define TECA_ALGORITHM_DELETE_COPY_ASSIGN(T)    \
-                                                \
-    T(const T &src) = delete;                   \
-    T(T &&src) = delete;                        \
-                                                \
-    T &operator=(const T &src) = delete;        \
-    T &operator=(T &&src) = delete;
-
-// convenience macro to declare standard set_NAME/get_NAME methods
-// where NAME is the name of a class member. will manage the
-// algorithm's modified state for the user.
-#define TECA_ALGORITHM_PROPERTY(T, NAME)                 \
-                                                         \
-/** Set the value of the @ref NAME algorithm property */ \
-void set_##NAME(const T &v)                              \
-{                                                        \
-    if (this->NAME != v)                                 \
-    {                                                    \
-        this->NAME = v;                                  \
-        this->set_modified();                            \
-    }                                                    \
-}                                                        \
-                                                         \
-/** Get the value of the @ref NAME algorithm property */ \
-const T &get_##NAME() const                              \
-{                                                        \
-    return this->NAME;                                   \
-}
-
-// similar to TECA_ALGORITHM_PROPERTY but prior to setting NAME
-// will call the member function int valididate_NAME(T v). If
-// the value v is valid the fucntion should return 0. If the value
-// is not zero the function should invoke TECA_ERROR with a
-// descriptive message and return non-zero.
-#define TECA_ALGORITHM_PROPERTY_V(T, NAME) \
-                                           \
-void set_##NAME(const T &v)                \
-{                                          \
-    if (this->validate_ ## NAME (v))       \
-        return;                            \
-                                           \
-    if (this->NAME != v)                   \
-    {                                      \
-        this->NAME = v;                    \
-        this->set_modified();              \
-    }                                      \
-}                                          \
-                                           \
-const T &get_##NAME() const                \
-{                                          \
-    return this->NAME;                     \
-}
-
-// convenience macro to declare standard set_NAME/get_NAME methods
-// where NAME is the name of a class member. will manage the
-// algorithm's modified state for the user.
-#define TECA_ALGORITHM_VECTOR_PROPERTY(T, NAME)                           \
-                                                                          \
-/** get the size of the @ref NAME##s algorithm vector property */         \
-size_t get_number_of_##NAME##s ()                                         \
-{                                                                         \
-    return this->NAME##s.size();                                          \
-}                                                                         \
-                                                                          \
-/** append to the @ref NAME##s algorithm vector property */               \
-void append_##NAME(const T &v)                                            \
-{                                                                         \
-    this->NAME##s.push_back(v);                                           \
-    this->set_modified();                                                 \
-}                                                                         \
-                                                                          \
-/** set the i-th element of the @ref NAME##s algorithm vector property */ \
-void set_##NAME(size_t i, const T &v)                                     \
-{                                                                         \
-    if (this->NAME##s[i] != v)                                            \
-    {                                                                     \
-        this->NAME##s[i] = v;                                             \
-        this->set_modified();                                             \
-    }                                                                     \
-}                                                                         \
-                                                                          \
-/** set the @ref NAME##s algorithm vector property */                     \
-void set_##NAME##s(const std::vector<T> &v)                               \
-{                                                                         \
-    if (this->NAME##s != v)                                               \
-    {                                                                     \
-        this->NAME##s = v;                                                \
-        this->set_modified();                                             \
-    }                                                                     \
-}                                                                         \
-                                                                          \
-/** set the @ref NAME##s algorithm vector property */                     \
-void set_##NAME##s(const std::initializer_list<T> &&l)                    \
-{                                                                         \
-    std::vector<T> v(l);                                                  \
-    if (this->NAME##s != v)                                               \
-    {                                                                     \
-        this->NAME##s = v;                                                \
-        this->set_modified();                                             \
-    }                                                                     \
-}                                                                         \
-                                                                          \
-/** get the i-th element of the @ref NAME##s algorithm vector property */ \
-const T &get_##NAME(size_t i) const                                       \
-{                                                                         \
-    return this->NAME##s[i];                                              \
-}                                                                         \
-                                                                          \
-/** get the @ref NAME##s algorithm vector property */                     \
-const std::vector<T> &get_##NAME##s() const                               \
-{                                                                         \
-    return this->NAME##s;                                                 \
-}                                                                         \
-                                                                          \
-/** clear the @ref NAME##s algorithm vector property */                   \
-void clear_##NAME##s()                                                    \
-{                                                                         \
-    this->NAME##s.clear();                                                \
-}
-
-
-// helper that allows us to use std::function
-// as a TECA_ALGORITHM_PROPERTY
-template<typename T>
-bool operator!=(const std::function<T> &lhs, const std::function<T> &rhs)
-{
-    return &rhs != &lhs;
-}
-
-// TODO -- this is a work around for older versions
-// of Apple clang
-// Apple LLVM version 4.2 (clang-425.0.28) (based on LLVM 3.2svn)
-// Target: x86_64-apple-darwin12.6.0
-#define TECA_ALGORITHM_CALLBACK_PROPERTY(T, NAME)   \
-                                                    \
-void set_##NAME(const T &v)                         \
-{                                                   \
-    /*if (this->NAME != v)*/                        \
-    /*{*/                                           \
-        this->NAME = v;                             \
-        this->set_modified();                       \
-    /*}*/                                           \
-}                                                   \
-                                                    \
-const T &get_##NAME() const                         \
-{                                                   \
-    return this->NAME;                              \
-}                                                   \
-                                                    \
-T &get_##NAME()                                     \
-{                                                   \
-    return this->NAME;                              \
-}
-
-#endif
diff --git a/core/teca_algorithm_output_port.h b/core/teca_algorithm_output_port.h
index 3e7921148..70cce15f1 100644
--- a/core/teca_algorithm_output_port.h
+++ b/core/teca_algorithm_output_port.h
@@ -1,15 +1,18 @@
 #ifndef teca_algorithm_output_port_h
 #define teca_algorithm_output_port_h
 
+/// @file
+
+/// An output port packages an algorithm and a port number
 using teca_algorithm_output_port
     = std::pair<p_teca_algorithm, unsigned int>;
 
-// convenience functions for accessing port and algorithm
-// from an output port
+/// get the algorithm from the output port
 inline
 p_teca_algorithm &get_algorithm(teca_algorithm_output_port &op)
 { return op.first; }
 
+/// get port number from the output port
 inline
 unsigned int &get_port(teca_algorithm_output_port &op)
 { return op.second; }
diff --git a/core/teca_dataset.h b/core/teca_dataset.h
index 81f405664..b8db4f646 100644
--- a/core/teca_dataset.h
+++ b/core/teca_dataset.h
@@ -1,12 +1,217 @@
 #ifndef teca_dataset_h
 #define teca_dataset_h
 
+#include "teca_common.h"
+#include "teca_shared_object.h"
 #include "teca_variant_array.h"
-#include "teca_dataset_fwd.h"
+
+#include <vector>
 #include <iosfwd>
+
 class teca_binary_stream;
 class teca_metadata;
 
+TECA_SHARED_OBJECT_FORWARD_DECL(teca_dataset)
+
+// this is a convenience macro to be used to
+// declare New and enable seamless operation
+// with std C++11 shared pointer
+#define TECA_DATASET_STATIC_NEW(T)                  \
+                                                    \
+static p_##T New()                                  \
+{                                                   \
+    return p_##T(new T);                            \
+}                                                   \
+                                                    \
+std::shared_ptr<T> shared_from_this()               \
+{                                                   \
+    return std::static_pointer_cast<T>(             \
+        teca_dataset::shared_from_this());          \
+}                                                   \
+                                                    \
+std::shared_ptr<T const> shared_from_this() const   \
+{                                                   \
+    return std::static_pointer_cast<T const>(       \
+        teca_dataset::shared_from_this());          \
+}
+
+// convenience macro implementing new_instance method
+#define TECA_DATASET_NEW_INSTANCE()                 \
+virtual p_teca_dataset new_instance() const override\
+{                                                   \
+    return this->New();                             \
+}
+
+// convenience macro implementing new_copy method
+#define TECA_DATASET_NEW_COPY()                     \
+virtual p_teca_dataset new_copy() const override    \
+{                                                   \
+    p_teca_dataset o = this->new_instance();        \
+    o->copy(this->shared_from_this());              \
+    return o;                                       \
+}                                                   \
+                                                    \
+virtual p_teca_dataset new_shallow_copy() override  \
+{                                                   \
+    p_teca_dataset o = this->new_instance();        \
+    o->shallow_copy(this->shared_from_this());      \
+    return o;                                       \
+}
+
+// convenience macro for adding properties to dataset
+// objects
+#define TECA_DATASET_PROPERTY(T, name)  \
+                                        \
+void set_##name(const T &val)           \
+{                                       \
+    this->name = val;                   \
+}                                       \
+                                        \
+const T &get_##name() const             \
+{                                       \
+    return this->name;                  \
+}                                       \
+                                        \
+T &get_##name()                         \
+{                                       \
+    return this->name;                  \
+}
+
+// convenience set get methods for dataset metadata
+#define TECA_DATASET_METADATA(key, T, len)          \
+TECA_DATASET_METADATA_V(T, key, len)                \
+TECA_DATASET_METADATA_A(T, key, len)                \
+TECA_DATASET_METADATA_ ## len (T, key)
+
+
+#define TECA_DATASET_METADATA_1(T, key)             \
+void set_##key(const T & val_1)                     \
+{                                                   \
+    this->get_metadata().set<T>(#key, val_1);       \
+}                                                   \
+                                                    \
+int get_##key(T &val_1) const                       \
+{                                                   \
+    return this->get_metadata().get<T>(             \
+        #key, val_1);                               \
+}
+
+#define TECA_DATASET_METADATA_2(T, key)             \
+void set_##key(const T & val_1, const T & val_2)    \
+{                                                   \
+    this->get_metadata().set<T>(                    \
+        #key, {val_1, val_2});                      \
+}                                                   \
+                                                    \
+int get_##key(T &val_1, T &val_2) const             \
+{                                                   \
+    std::vector<T> vals;                            \
+    if (this->get_metadata().get<T>(#key, vals))    \
+        return -1;                                  \
+    val_1 = vals[0];                                \
+    val_2 = vals[1];                                \
+    return 0;                                       \
+}
+
+#define TECA_DATASET_METADATA_3(T, key)             \
+void set_##key(const T & val_1, const T & val_2,    \
+    const T & val_3)                                \
+{                                                   \
+    this->get_metadata().set<T>(#key,               \
+        {val_1, val_2, val_3});                     \
+}                                                   \
+                                                    \
+int get_##key(T &val_1, T &val_2, T &val_3) const   \
+{                                                   \
+    std::vector<T> vals;                            \
+    if (this->get_metadata().get<T>(#key, vals))    \
+        return -1;                                  \
+    val_1 = vals[0];                                \
+    val_2 = vals[1];                                \
+    val_3 = vals[2];                                \
+    return 0;                                       \
+}
+
+#define TECA_DATASET_METADATA_4(T, key)             \
+void set_##key(const T & val_1, const T & val_2,    \
+    const T & val_3, const T & val_4)               \
+{                                                   \
+    this->get_metadata().set<T>(#key,               \
+         {val_1, val_2, val_3, val_4});             \
+}
+
+#define TECA_DATASET_METADATA_6(T, key)             \
+void set_##key(const T & val_1, const T & val_2,    \
+    const T & val_3, const T & val_4,               \
+    const T & val_5, const T & val_6)               \
+{                                                   \
+    this->get_metadata().set<T>(#key,               \
+        {val_1, val_2, val_3,                       \
+        val_4, val_5, val_6});                      \
+}
+
+#define TECA_DATASET_METADATA_8(T, key)             \
+void set_##key(const T & val_1, const T & val_2,    \
+    const T & val_3, const T & val_4,               \
+    const T & val_5, const T & val_6,               \
+    const T & val_7, const T & val_8)               \
+{                                                   \
+    this->get_metadata().set<T>(#key,               \
+        {val_1, val_2, val_3, val_4, val_5,         \
+         val_6, val_7, val_8});                     \
+}
+
+#define TECA_DATASET_METADATA_V(T, key, len)            \
+void set_##key(const std::vector<T> &vals)              \
+{                                                       \
+    if (vals.size() != len)                             \
+    {                                                   \
+        TECA_ERROR(#key " requires " #len " values")    \
+    }                                                   \
+    this->get_metadata().set<T>(#key, vals);            \
+}                                                       \
+                                                        \
+int get_##key(std::vector<T> &vals) const               \
+{                                                       \
+    return this->get_metadata().get<T>(#key, vals);     \
+}                                                       \
+                                                        \
+void set_##key(const p_teca_variant_array &vals)        \
+{                                                       \
+    if (vals->size() != len)                            \
+    {                                                   \
+        TECA_ERROR(#key " requires " #len " values")    \
+    }                                                   \
+    this->get_metadata().set(#key, vals);               \
+}                                                       \
+                                                        \
+int get_##key(p_teca_variant_array vals) const          \
+{                                                       \
+    return this->get_metadata().get(#key, vals);        \
+}                                                       \
+                                                        \
+void set_##key(const std::initializer_list<T> &l)       \
+{                                                       \
+    std::vector<T> vals(l);                             \
+    if (vals.size() != len)                             \
+    {                                                   \
+        TECA_ERROR(#key " requires " #len " values")    \
+    }                                                   \
+    this->get_metadata().set<T>(#key, vals);            \
+}                                                       \
+
+#define TECA_DATASET_METADATA_A(T, key, len)            \
+void set_##key(const T *vals)                           \
+{                                                       \
+    this->get_metadata().set<T>(#key, vals, len);       \
+}                                                       \
+                                                        \
+int get_##key(T *vals) const                            \
+{                                                       \
+    return this->get_metadata().get<T>(                 \
+        #key, vals, len);                               \
+}
+
 /// Interface for TECA datasets.
 class teca_dataset : public std::enable_shared_from_this<teca_dataset>
 {
diff --git a/core/teca_dataset_capture.h b/core/teca_dataset_capture.h
index e457a8fab..52e8007c0 100644
--- a/core/teca_dataset_capture.h
+++ b/core/teca_dataset_capture.h
@@ -3,7 +3,7 @@
 
 #include "teca_algorithm.h"
 #include "teca_metadata.h"
-#include "teca_dataset_fwd.h"
+#include "teca_dataset.h"
 #include "teca_shared_object.h"
 
 TECA_SHARED_OBJECT_FORWARD_DECL(teca_dataset_capture)
diff --git a/core/teca_dataset_fwd.h b/core/teca_dataset_fwd.h
deleted file mode 100644
index 46fd125d9..000000000
--- a/core/teca_dataset_fwd.h
+++ /dev/null
@@ -1,210 +0,0 @@
-#ifndef teca_dataset_fwd_h
-#define teca_dataset_fwd_h
-
-#include "teca_common.h"
-#include "teca_shared_object.h"
-
-#include <vector>
-
-TECA_SHARED_OBJECT_FORWARD_DECL(teca_dataset)
-
-// this is a convenience macro to be used to
-// declare New and enable seamless operation
-// with std C++11 shared pointer
-#define TECA_DATASET_STATIC_NEW(T)                  \
-                                                    \
-static p_##T New()                                  \
-{                                                   \
-    return p_##T(new T);                            \
-}                                                   \
-                                                    \
-std::shared_ptr<T> shared_from_this()               \
-{                                                   \
-    return std::static_pointer_cast<T>(             \
-        teca_dataset::shared_from_this());          \
-}                                                   \
-                                                    \
-std::shared_ptr<T const> shared_from_this() const   \
-{                                                   \
-    return std::static_pointer_cast<T const>(       \
-        teca_dataset::shared_from_this());          \
-}
-
-// convenience macro implementing new_instance method
-#define TECA_DATASET_NEW_INSTANCE()                 \
-virtual p_teca_dataset new_instance() const override\
-{                                                   \
-    return this->New();                             \
-}
-
-// convenience macro implementing new_copy method
-#define TECA_DATASET_NEW_COPY()                     \
-virtual p_teca_dataset new_copy() const override    \
-{                                                   \
-    p_teca_dataset o = this->new_instance();        \
-    o->copy(this->shared_from_this());              \
-    return o;                                       \
-}                                                   \
-                                                    \
-virtual p_teca_dataset new_shallow_copy() override  \
-{                                                   \
-    p_teca_dataset o = this->new_instance();        \
-    o->shallow_copy(this->shared_from_this());      \
-    return o;                                       \
-}
-
-// convenience macro for adding properties to dataset
-// objects
-#define TECA_DATASET_PROPERTY(T, name)  \
-                                        \
-void set_##name(const T &val)           \
-{                                       \
-    this->name = val;                   \
-}                                       \
-                                        \
-const T &get_##name() const             \
-{                                       \
-    return this->name;                  \
-}                                       \
-                                        \
-T &get_##name()                         \
-{                                       \
-    return this->name;                  \
-}
-
-// convenience set get methods for dataset metadata
-#define TECA_DATASET_METADATA(key, T, len)          \
-TECA_DATASET_METADATA_V(T, key, len)                \
-TECA_DATASET_METADATA_A(T, key, len)                \
-TECA_DATASET_METADATA_ ## len (T, key)
-
-
-#define TECA_DATASET_METADATA_1(T, key)             \
-void set_##key(const T & val_1)                     \
-{                                                   \
-    this->get_metadata().set<T>(#key, val_1);       \
-}                                                   \
-                                                    \
-int get_##key(T &val_1) const                       \
-{                                                   \
-    return this->get_metadata().get<T>(             \
-        #key, val_1);                               \
-}
-
-#define TECA_DATASET_METADATA_2(T, key)             \
-void set_##key(const T & val_1, const T & val_2)    \
-{                                                   \
-    this->get_metadata().set<T>(                    \
-        #key, {val_1, val_2});                      \
-}                                                   \
-                                                    \
-int get_##key(T &val_1, T &val_2) const             \
-{                                                   \
-    std::vector<T> vals;                            \
-    if (this->get_metadata().get<T>(#key, vals))    \
-        return -1;                                  \
-    val_1 = vals[0];                                \
-    val_2 = vals[1];                                \
-    return 0;                                       \
-}
-
-#define TECA_DATASET_METADATA_3(T, key)             \
-void set_##key(const T & val_1, const T & val_2,    \
-    const T & val_3)                                \
-{                                                   \
-    this->get_metadata().set<T>(#key,               \
-        {val_1, val_2, val_3});                     \
-}                                                   \
-                                                    \
-int get_##key(T &val_1, T &val_2, T &val_3) const   \
-{                                                   \
-    std::vector<T> vals;                            \
-    if (this->get_metadata().get<T>(#key, vals))    \
-        return -1;                                  \
-    val_1 = vals[0];                                \
-    val_2 = vals[1];                                \
-    val_3 = vals[2];                                \
-    return 0;                                       \
-}
-
-#define TECA_DATASET_METADATA_4(T, key)             \
-void set_##key(const T & val_1, const T & val_2,    \
-    const T & val_3, const T & val_4)               \
-{                                                   \
-    this->get_metadata().set<T>(#key,               \
-         {val_1, val_2, val_3, val_4});             \
-}
-
-#define TECA_DATASET_METADATA_6(T, key)             \
-void set_##key(const T & val_1, const T & val_2,    \
-    const T & val_3, const T & val_4,               \
-    const T & val_5, const T & val_6)               \
-{                                                   \
-    this->get_metadata().set<T>(#key,               \
-        {val_1, val_2, val_3,                       \
-        val_4, val_5, val_6});                      \
-}
-
-#define TECA_DATASET_METADATA_8(T, key)             \
-void set_##key(const T & val_1, const T & val_2,    \
-    const T & val_3, const T & val_4,               \
-    const T & val_5, const T & val_6,               \
-    const T & val_7, const T & val_8)               \
-{                                                   \
-    this->get_metadata().set<T>(#key,               \
-        {val_1, val_2, val_3, val_4, val_5,         \
-         val_6, val_7, val_8});                     \
-}
-
-#define TECA_DATASET_METADATA_V(T, key, len)            \
-void set_##key(const std::vector<T> &vals)              \
-{                                                       \
-    if (vals.size() != len)                             \
-    {                                                   \
-        TECA_ERROR(#key " requires " #len " values")    \
-    }                                                   \
-    this->get_metadata().set<T>(#key, vals);            \
-}                                                       \
-                                                        \
-int get_##key(std::vector<T> &vals) const               \
-{                                                       \
-    return this->get_metadata().get<T>(#key, vals);     \
-}                                                       \
-                                                        \
-void set_##key(const p_teca_variant_array &vals)        \
-{                                                       \
-    if (vals->size() != len)                            \
-    {                                                   \
-        TECA_ERROR(#key " requires " #len " values")    \
-    }                                                   \
-    this->get_metadata().set(#key, vals);               \
-}                                                       \
-                                                        \
-int get_##key(p_teca_variant_array vals) const          \
-{                                                       \
-    return this->get_metadata().get(#key, vals);        \
-}                                                       \
-                                                        \
-void set_##key(const std::initializer_list<T> &l)       \
-{                                                       \
-    std::vector<T> vals(l);                             \
-    if (vals.size() != len)                             \
-    {                                                   \
-        TECA_ERROR(#key " requires " #len " values")    \
-    }                                                   \
-    this->get_metadata().set<T>(#key, vals);            \
-}                                                       \
-
-#define TECA_DATASET_METADATA_A(T, key, len)            \
-void set_##key(const T *vals)                           \
-{                                                       \
-    this->get_metadata().set<T>(#key, vals, len);       \
-}                                                       \
-                                                        \
-int get_##key(T *vals) const                            \
-{                                                       \
-    return this->get_metadata().get<T>(                 \
-        #key, vals, len);                               \
-}
-
-#endif
diff --git a/core/teca_dataset_source.h b/core/teca_dataset_source.h
index f5e3f9542..b7f96cf6d 100644
--- a/core/teca_dataset_source.h
+++ b/core/teca_dataset_source.h
@@ -3,7 +3,7 @@
 
 #include "teca_algorithm.h"
 #include "teca_metadata.h"
-#include "teca_dataset_fwd.h"
+#include "teca_dataset.h"
 #include "teca_shared_object.h"
 
 #include <vector>
diff --git a/core/teca_index_executive.h b/core/teca_index_executive.h
index 2640811cd..8c70d9ece 100644
--- a/core/teca_index_executive.h
+++ b/core/teca_index_executive.h
@@ -10,16 +10,12 @@
 
 TECA_SHARED_OBJECT_FORWARD_DECL(teca_index_executive)
 
-/** @brief
- * An executive that generates requests using a upstream
- * or user defined index.
- *
- * @details
- * An extent and list of arrays can be optionally set.
+/// An executive that generates requests using a upstream or user defined index.
+/** An extent or bounds to subset by, and list of arrays can be optionally set.
  *
  * metadata keys:
  *
- *      requires:
+ * requires:
  *
  *      index_initializer_key -- holds the name of the key that tells how
  *                               many indices are available. the named key
@@ -40,33 +36,33 @@ class teca_index_executive : public teca_algorithm_executive
     int initialize(MPI_Comm comm, const teca_metadata &md) override;
     teca_metadata get_next_request() override;
 
-    // set the index to process
+    /// set the index to process
     void set_index(long s);
 
-    // set the first time step in the series to process.
-    // default is 0.
+    // Set the first time step in the series to process. The default is 0.
     void set_start_index(long s);
 
-    // set the last time step in the series to process.
-    // default is -1. negative number results in the last
-    // available time step being used.
+    /** Set the last time step in the series to process.  default is -1.
+     * negative number results in the last available time step being used.
+     */
     void set_end_index(long s);
 
-    // set the stride to process time steps at. default
-    // is 1
+    /// Set the stride to process time steps at. The default is 1
     void set_stride(long s);
 
-    // set the extent to process. the default is the
-    // whole_extent.
+    /// Set the extent to process. The default is taken from whole_extent key.
     void set_extent(unsigned long *ext);
+
+    /// @copydoc set_extent
     void set_extent(const std::vector<unsigned long> &ext);
 
-    // set the bounds to process. If nothing is set then
-    // extent as provided by set_extent is used.
+    /** Set the bounds to process. If nothing is set then extent as provided by
+     * set_extent is used.
+     */
     void set_bounds(double *bounds);
     void set_bounds(const std::vector<double> &bounds);
 
-    // set the list of arrays to process
+    /// Set the list of arrays to process
     void set_arrays(const std::vector<std::string> &arrays);
 
 protected:
diff --git a/core/teca_index_reduce.h b/core/teca_index_reduce.h
index 0812cf771..85dae1786 100644
--- a/core/teca_index_reduce.h
+++ b/core/teca_index_reduce.h
@@ -1,14 +1,15 @@
 #ifndef teca_index_reduce_h
 #define teca_index_reduce_h
 
-#include "teca_dataset_fwd.h"
-#include "teca_index_reduce_fwd.h"
-
-#include "teca_threaded_algorithm.h"
+#include "teca_dataset.h"
 #include "teca_metadata.h"
+#include "teca_shared_object.h"
+#include "teca_threaded_algorithm.h"
 
 #include <vector>
 
+TECA_SHARED_OBJECT_FORWARD_DECL(teca_index_reduce)
+
 /// Base class for MPI + threads map reduce reduction over an index.
 /**
  * The available indices are partitioned across MPI ranks and threads. One can
diff --git a/core/teca_index_reduce_fwd.h b/core/teca_index_reduce_fwd.h
deleted file mode 100644
index 6f977040a..000000000
--- a/core/teca_index_reduce_fwd.h
+++ /dev/null
@@ -1,8 +0,0 @@
-#ifndef teca_index_reduce_fwd_h
-#define teca_index_reduce_fwd_h
-
-#include "teca_shared_object.h"
-
-TECA_SHARED_OBJECT_FORWARD_DECL(teca_index_reduce)
-
-#endif
diff --git a/core/teca_parallel_id.h b/core/teca_parallel_id.h
index 84c87420e..cbaab317d 100644
--- a/core/teca_parallel_id.h
+++ b/core/teca_parallel_id.h
@@ -1,6 +1,8 @@
 #ifndef teca_parallel_id_h
 #define teca_parallel_id_h
 
+/// @file
+
 #include <iosfwd>
 
 /// A helper class for debug and error messages.
diff --git a/core/teca_program_options.h b/core/teca_program_options.h
index d2e2ecca1..83a9f1771 100644
--- a/core/teca_program_options.h
+++ b/core/teca_program_options.h
@@ -1,6 +1,8 @@
 #ifndef teca_program_options_h
 #define teca_program_options_h
 
+/// @file
+
 #include "teca_config.h"
 #include "teca_common.h"
 #include "teca_mpi_util.h"
@@ -15,25 +17,21 @@ namespace boost
     }
 };
 
-using options_description
-    = boost::program_options::options_description;
-
-using variables_map
-    = boost::program_options::variables_map;
+using options_description = boost::program_options::options_description;
+using variables_map = boost::program_options::variables_map;
 
-// initialize the given options description
-// with algorithm's properties
-#define TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION() \
-    void get_properties_description(                \
-        const std::string &prefix,                  \
-        options_description &opts) override;        \
+/// initialize the given options description with algorithm's properties
+#define TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()                         \
+                                                                            \
+    /** Adds the class algorithm properties to the description object */    \
+    void get_properties_description(const std::string &prefix,              \
+        boost::program_options::options_description &opts) override;        \
 
-// initialize the algorithm from the given options
-// variable map.
-#define TECA_SET_ALGORITHM_PROPERTIES()             \
-    void set_properties(                            \
-        const std::string &prefix,                  \
-        variables_map &opts) override;              \
+/// initialize the algorithm from the given options variable map.
+#define TECA_SET_ALGORITHM_PROPERTIES()                                     \
+    /** Sets the class algorithm properties from the map object */          \
+    void set_properties(const std::string &prefix,                          \
+        boost::program_options::variables_map &opts) override;              \
 
 // helpers for implementation dealing with Boost
 // program options. NOTE: because the above declarations
diff --git a/core/teca_programmable_algorithm.h b/core/teca_programmable_algorithm.h
index a798105b4..bb4f0a449 100644
--- a/core/teca_programmable_algorithm.h
+++ b/core/teca_programmable_algorithm.h
@@ -2,9 +2,38 @@
 #define teca_programmable_algorithm_h
 
 #include "teca_algorithm.h"
+#include "teca_shared_object.h"
 #include "teca_metadata.h"
-#include "teca_dataset_fwd.h"
-#include "teca_programmable_algorithm_fwd.h"
+#include "teca_dataset.h"
+
+TECA_SHARED_OBJECT_FORWARD_DECL(teca_programmable_algorithm)
+TECA_SHARED_OBJECT_FORWARD_DECL(teca_threaded_programmable_algorithm)
+
+#ifdef SWIG
+typedef void* report_callback_t;
+typedef void* request_callback_t;
+typedef void* execute_callback_t;
+typedef void* threaded_execute_callback_t;
+#else
+/// A callable implementing the report phase of pipeline execution
+using report_callback_t = std::function<teca_metadata(
+        unsigned int, const std::vector<teca_metadata>&)>;
+
+/// A callable implementing the request phase of pipeline execution
+using request_callback_t = std::function<std::vector<teca_metadata>(
+        unsigned int, const std::vector<teca_metadata> &,
+        const teca_metadata &)>;
+
+/// A callable implementing the execute phase of pipeline execution
+using execute_callback_t = std::function<const_p_teca_dataset(
+        unsigned int, const std::vector<const_p_teca_dataset> &,
+        const teca_metadata &)>;
+
+/// A callable implementing the streaming execute phase of pipeline execution
+using threaded_execute_callback_t = std::function<const_p_teca_dataset(
+        unsigned int, const std::vector<const_p_teca_dataset> &,
+        const teca_metadata &, int)>;
+#endif
 
 /// An algorithm implemented with  user provided callbacks.
 /**
diff --git a/core/teca_programmable_algorithm_fwd.h b/core/teca_programmable_algorithm_fwd.h
deleted file mode 100644
index 626fcfd57..000000000
--- a/core/teca_programmable_algorithm_fwd.h
+++ /dev/null
@@ -1,32 +0,0 @@
-#ifndef teca_program_algorithm_fwd_h
-#define teca_program_algorithm_fwd_h
-
-#include "teca_shared_object.h"
-#include "teca_metadata.h"
-#include "teca_dataset_fwd.h"
-
-TECA_SHARED_OBJECT_FORWARD_DECL(teca_programmable_algorithm)
-TECA_SHARED_OBJECT_FORWARD_DECL(teca_threaded_programmable_algorithm)
-
-#ifdef SWIG
-typedef void* report_callback_t;
-typedef void* request_callback_t;
-typedef void* execute_callback_t;
-typedef void* threaded_execute_callback_t;
-#else
-using report_callback_t = std::function<teca_metadata(
-        unsigned int, const std::vector<teca_metadata>&)>;
-
-using request_callback_t = std::function<std::vector<teca_metadata>(
-        unsigned int, const std::vector<teca_metadata> &,
-        const teca_metadata &)>;
-
-using execute_callback_t = std::function<const_p_teca_dataset(
-        unsigned int, const std::vector<const_p_teca_dataset> &,
-        const teca_metadata &)>;
-
-using threaded_execute_callback_t = std::function<const_p_teca_dataset(
-        unsigned int, const std::vector<const_p_teca_dataset> &,
-        const teca_metadata &, int)>;
-#endif
-#endif
diff --git a/core/teca_programmable_reduce.h b/core/teca_programmable_reduce.h
index cdb237d0e..f4bade029 100644
--- a/core/teca_programmable_reduce.h
+++ b/core/teca_programmable_reduce.h
@@ -1,14 +1,30 @@
 #ifndef teca_programmable_reduce_h
 #define teca_programmable_reduce_h
 
-#include "teca_programmable_reduce_fwd.h"
-#include "teca_programmable_algorithm_fwd.h"
-#include "teca_index_reduce.h"
-#include "teca_dataset_fwd.h"
+#include "teca_dataset.h"
 #include "teca_metadata.h"
+#include "teca_shared_object.h"
+#include "teca_programmable_algorithm.h"
+#include "teca_index_reduce.h"
 
 #include <string>
 #include <vector>
+#include <functional>
+
+TECA_SHARED_OBJECT_FORWARD_DECL(teca_programmable_reduce)
+
+#ifdef SWIG
+typedef void* reduce_callback_t;
+typedef void* finalize_callback_t;
+#else
+/// A callable that can reduce two datasets into one.
+using reduce_callback_t = std::function<p_teca_dataset(
+    const const_p_teca_dataset &, const const_p_teca_dataset &)>;
+
+/// A callable that can finalize the reduction.
+using finalize_callback_t = std::function<p_teca_dataset(
+    const const_p_teca_dataset &)>;
+#endif
 
 /// Callbacks implement a user defined reduction over time steps.
 /**
diff --git a/core/teca_programmable_reduce_fwd.h b/core/teca_programmable_reduce_fwd.h
deleted file mode 100644
index e17706fae..000000000
--- a/core/teca_programmable_reduce_fwd.h
+++ /dev/null
@@ -1,20 +0,0 @@
-#ifndef teca_program_reduce_fwd_h
-#define teca_program_reduce_fwd_h
-
-#include "teca_shared_object.h"
-#include "teca_dataset_fwd.h"
-#include <functional>
-
-TECA_SHARED_OBJECT_FORWARD_DECL(teca_programmable_reduce)
-
-#ifdef SWIG
-typedef void* reduce_callback_t;
-typedef void* finalize_callback_t;
-#else
-using reduce_callback_t = std::function<p_teca_dataset(
-    const const_p_teca_dataset &, const const_p_teca_dataset &)>;
-
-using finalize_callback_t = std::function<p_teca_dataset(
-    const const_p_teca_dataset &)>;
-#endif
-#endif
diff --git a/core/teca_shared_object.h b/core/teca_shared_object.h
index 015c7d5af..739561127 100644
--- a/core/teca_shared_object.h
+++ b/core/teca_shared_object.h
@@ -1,14 +1,19 @@
 #ifndef teca_shared_object_h
 #define teca_shared_object_h
 
+/// @file
+
 #include <memory>
 
 // convenience macro. every teca_algrotihm/dataset
 // should have the following forward declarations
+
 #ifdef SWIG
+
 // SWIG doesn't handle alias templates yet. OK for the
 // shared object forward but the shared object template
 // forward has no direct mapping into c++03.
+
 #define TECA_SHARED_OBJECT_FORWARD_DECL(_cls)           \
     class _cls;                                         \
     typedef std::shared_ptr<_cls> p_##_cls;             \
@@ -16,19 +21,28 @@
 
 #define TECA_SHARED_OBJECT_TEMPLATE_FORWARD_DECL(_cls)  \
     template<typename T> class _cls;
+
 #else
+
 #define TECA_SHARED_OBJECT_FORWARD_DECL(_cls)           \
     class _cls;                                         \
+                                                        \
+    /** a shared pointer to an instance of _cls */      \
     using p_##_cls = std::shared_ptr<_cls>;             \
+                                                        \
+    /** A shared pointer to a const instance of _cls */ \
     using const_p_##_cls = std::shared_ptr<const _cls>;
 
 #define TECA_SHARED_OBJECT_TEMPLATE_FORWARD_DECL(_cls)  \
     template<typename T> class _cls;                    \
                                                         \
+    /** a shared pointer to an instance of _cls */      \
     template<typename T>                                \
     using p_##_cls = std::shared_ptr<_cls<T>>;          \
                                                         \
+    /** A shared pointer to a const instance of _cls */ \
     template<typename T>                                \
     using const_p_##_cls = std::shared_ptr<const _cls<T>>;
+
 #endif
 #endif
diff --git a/core/teca_thread_pool.h b/core/teca_thread_pool.h
index 2cf88d2d2..9c31bf704 100644
--- a/core/teca_thread_pool.h
+++ b/core/teca_thread_pool.h
@@ -2,7 +2,7 @@
 #define teca_thread_pool_h
 
 #include "teca_common.h"
-#include "teca_algorithm_fwd.h"
+#include "teca_algorithm.h"
 #include "teca_thread_util.h"
 #include "teca_threadsafe_queue.h"
 #include "teca_mpi.h"
diff --git a/core/teca_threaded_algorithm.h b/core/teca_threaded_algorithm.h
index f5d22ffc8..77451662b 100644
--- a/core/teca_threaded_algorithm.h
+++ b/core/teca_threaded_algorithm.h
@@ -2,9 +2,11 @@
 #define teca_threaded_algorithm_h
 
 #include "teca_algorithm.h"
-#include "teca_threaded_algorithm_fwd.h"
-#include "teca_algorithm_output_port.h"
 #include "teca_dataset.h"
+#include "teca_shared_object.h"
+
+#include <thread>
+#include <future>
 
 template <typename task_t, typename data_t>
 class teca_thread_pool;
@@ -12,18 +14,27 @@ class teca_thread_pool;
 class teca_metadata;
 class teca_threaded_algorithm_internals;
 
-#include <thread>
-#include <future>
+TECA_SHARED_OBJECT_FORWARD_DECL(teca_threaded_algorithm)
 
-// declare the thread pool type
+/// Task type for tasks returing a pointer to teca_dataset
 using teca_data_request_task = std::packaged_task<const_p_teca_dataset()>;
 
 class teca_data_request;
+
+/// A thread pool for processing teca_data_request_task
 using teca_data_request_queue =
     teca_thread_pool<teca_data_request_task, const_p_teca_dataset>;
 
+/// A pointer to teca_data_request_queue
 using p_teca_data_request_queue = std::shared_ptr<teca_data_request_queue>;
 
+/** Allocate and initialize a new thread pool.
+ * comm [in] The communicator to allocate thread across
+ * n [in] The number of threads to create per MPI rank. Use -1 to
+ *        map one thread per physical core on each node.
+ * bind [in] If set then thread will be bound to a specific core.
+ * verbose [in] If set then the mapping is sent to the stderr
+ */
 p_teca_data_request_queue new_teca_data_request_queue(MPI_Comm comm,
     int n, bool bind, bool verbose);
 
@@ -45,29 +56,46 @@ class teca_threaded_algorithm : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    // set/get the number of threads in the pool. setting
-    // to -1 results in a thread per core factoring in all MPI
-    // ranks running on the node. the default is -1.
+    /** Set the number of threads in the pool. setting to -1 results in a
+     * thread per core factoring in all MPI ranks running on the node.
+     */
     void set_thread_pool_size(int n_threads);
-    unsigned int get_thread_pool_size() const noexcept;
-
-    // set/get the verbosity level.
-    TECA_ALGORITHM_PROPERTY(int, verbose);
 
-    // set/get thread affinity mode. When 0 threads are not bound
-    // CPU cores, allowing for migration among all cores. This will
-    // likely degrade performance. Default is 1.
-    TECA_ALGORITHM_PROPERTY(int, bind_threads);
-
-    // set the smallest number of datasets to gather per call to
-    // execute. the default (-1) results in all datasets being
-    // gathered. In practice more datasets will be returned if
-    // ready
-    TECA_ALGORITHM_PROPERTY(int, stream_size);
+    /// Get the number of threads in the pool.
+    unsigned int get_thread_pool_size() const noexcept;
 
-    // set the duration in nanoseconds to wait between checking
-    // for completed tasks
-    TECA_ALGORITHM_PROPERTY(long long, poll_interval);
+    /** @name verbose
+     * set/get the verbosity level.
+     */
+    ///@{
+    TECA_ALGORITHM_PROPERTY(int, verbose)
+    ///@}
+
+    /** @name bind_threads
+     * set/get thread affinity mode. When 0 threads are not bound CPU cores,
+     * allowing for migration among all cores. This will likely degrade
+     * performance. Default is 1.
+     */
+    ///@{
+    TECA_ALGORITHM_PROPERTY(int, bind_threads)
+    ///@}
+
+    /** @name stream_size
+     * set the smallest number of datasets to gather per call to execute. the
+     * default (-1) results in all datasets being gathered. In practice more
+     * datasets will be returned if ready
+     */
+    ///@{
+    TECA_ALGORITHM_PROPERTY(int, stream_size)
+    ///@}
+
+    /** @name poll_interval
+     * set the duration in nanoseconds to wait between checking for completed
+     * tasks
+     */
+    ///@{
+    TECA_ALGORITHM_PROPERTY(long long, poll_interval)
+    ///@}
 
     // explicitly set the thread pool to submit requests to
     void set_data_request_queue(const p_teca_data_request_queue &queue);
diff --git a/core/teca_threaded_algorithm_fwd.h b/core/teca_threaded_algorithm_fwd.h
deleted file mode 100644
index 5d3eb6fef..000000000
--- a/core/teca_threaded_algorithm_fwd.h
+++ /dev/null
@@ -1,8 +0,0 @@
-#ifndef teca_threaded_algorithm_fwd_h
-#define teca_threaded_algorithm_fwd_h
-
-#include "teca_shared_object.h"
-
-TECA_SHARED_OBJECT_FORWARD_DECL(teca_threaded_algorithm)
-
-#endif
diff --git a/core/teca_threaded_programmable_algorithm.h b/core/teca_threaded_programmable_algorithm.h
index 3246afac9..444748b0a 100644
--- a/core/teca_threaded_programmable_algorithm.h
+++ b/core/teca_threaded_programmable_algorithm.h
@@ -2,12 +2,11 @@
 #define teca_threaded_programmable_algorithm_h
 
 #include "teca_metadata.h"
+#include "teca_dataset.h"
 #include "teca_threaded_algorithm.h"
-#include "teca_dataset_fwd.h"
+#include "teca_programmable_algorithm.h"
 
-#include "teca_programmable_algorithm_fwd.h"
-
-/// An algorithm implemented with  user provided callbacks.
+/// An threaded algorithm implemented with user provided callbacks.
 /**
  * This version of the teca_programmable_algorithm is threaded. A thread pool
  * (call set_thread_pool_size to initialize) executes the upstream pipeline
@@ -23,33 +22,33 @@
  * can also be set for filters (1 or more inputs, 1 or more outputs)
  * sources, (no  inputs, 1 or more outputs), or sinks (1 or more
  * inputs, no outputs).
- * 
+ *
  * 1) report phase. the report callback returns metadata
  *     describing data that can be produced. The report callback
  *     is optional. It's only needed if the algorithm will produce
  *     new data or transform metadata.
- * 
+ *
  *     the report callback must be callable with signature:
  *     teca_metadata(unsigned int)
- * 
+ *
  * 2) request phase. the request callback generates a vector of
  *     requests(metadata objects) that inform the upstream of
  *     what data to generate. The request callback is optional.
  *     It's only needed if the algorithm needs data from the
  *     upstream or transform metadata.
- * 
+ *
  *     the request callback must be callable with the signature:
  *     std::vector<teca_metadata>(
  *         unsigned int,
  *         const std::vector<teca_metadata> &,
  *         const teca_metadata &)
- * 
+ *
  * 3) execute phase. the execute callback is used to do useful
  *     work on incoming or outgoing data. Examples include
  *     generating new datasets, processing datasets, reading
  *     and writing data to/from disk, and so on. The execute
  *     callback is  optional.
- * 
+ *
  *     the execute callback must be callable with the signature:
  *     const_p_teca_dataset(
  *         unsigned int, const std::vector<const_p_teca_dataset> &,
@@ -80,7 +79,7 @@ class teca_threaded_programmable_algorithm : public teca_threaded_algorithm
     using teca_algorithm::set_number_of_input_connections;
     using teca_algorithm::set_number_of_output_ports;
 
-    // set the number of threads. The default is -1. 
+    // set the number of threads. The default is -1.
     using teca_threaded_algorithm::set_thread_pool_size;
 
     // set the stream size. the default -1 disables streaming.
diff --git a/core/teca_threadsafe_queue.h b/core/teca_threadsafe_queue.h
index 66fdde37f..a15769686 100644
--- a/core/teca_threadsafe_queue.h
+++ b/core/teca_threadsafe_queue.h
@@ -5,7 +5,7 @@
 #include <queue>
 #include <condition_variable>
 
-/// TODO: Write documentation fro teca_threadsafe_queue
+/// A thread safe queue
 template<typename T>
 class teca_threadsafe_queue
 {
diff --git a/core/teca_type_select.h b/core/teca_type_select.h
index c480465d6..a372f706d 100644
--- a/core/teca_type_select.h
+++ b/core/teca_type_select.h
@@ -1,28 +1,45 @@
 #ifndef teca_type_elevate_h
 #define teca_type_elevate_h
 
+/// @file
+
+/// Select a type based on input type(s)
 namespace teca_type_select
 {
-// given two arguments, an elevate cast, selects
-// the type of or casts to the higher precision
-// type. note that given a signed and unsigned
-// argument, signed type is selected.
+/// Select the higher precision type.
+/** Given two arguments, an elevate cast, selects the type of or casts to the
+ * higher precision type. note that given a signed and unsigned argument,
+ * signed type is selected.
+ *
+ * @tparam t1 first input type
+ * @tparam t2 second input type
+ */
 template <typename t1, typename t2>
 struct elevate {};
 
-// given two areuments, a decay cast, selects the
-// type of or casts to the lower precision
-// type. note that given a signed and unsigned
-// argument, unsigned type is selected.
+/// Select the lower precision type.
+/** Given two arguments, a decay cast, selects the type of or casts to the lower
+ * precision type. note that given a signed and unsigned argument, unsigned
+ * type is selected.
+ *
+ * @tparam t1 first input type
+ * @tparam t2 second input type
+ */
 template <typename t1, typename t2>
 struct decay {};
 
 #define teca_type_select(_class, _ret, _t1, _t2)    \
+/** Given _t1 and _t2 _class to _ret */             \
 template <>                                         \
 struct _class<_t1, _t2>                             \
 {                                                   \
+    /** _class result type */                       \
     using type = _ret;                              \
+                                                    \
+    /** cast to _ret */                             \
     static _ret cast(_t1 arg){ return arg; }        \
+                                                    \
+    /** name of the _class result type */           \
     static constexpr const char *type_name()        \
     { return #_ret; }                               \
 };
diff --git a/core/teca_variant_array.h b/core/teca_variant_array.h
index 9bb540738..4d34243b2 100644
--- a/core/teca_variant_array.h
+++ b/core/teca_variant_array.h
@@ -1,7 +1,7 @@
 #ifndef teca_variant_array_h
 #define teca_variant_array_h
 
-/** @file */
+/// @file
 
 #include <vector>
 #include <string>
@@ -16,8 +16,119 @@
 
 #include "teca_common.h"
 #include "teca_binary_stream.h"
-#include "teca_variant_array_fwd.h"
 #include "teca_bad_cast.h"
+#include "teca_shared_object.h"
+
+TECA_SHARED_OBJECT_FORWARD_DECL(teca_variant_array)
+TECA_SHARED_OBJECT_TEMPLATE_FORWARD_DECL(teca_variant_array_impl)
+
+#ifndef SWIG
+using teca_string_array = teca_variant_array_impl<std::string>;
+using p_teca_string_array = std::shared_ptr<teca_variant_array_impl<std::string>>;
+using const_p_teca_string_array = std::shared_ptr<const teca_variant_array_impl<std::string>>;
+
+using teca_float_array = teca_variant_array_impl<float>;
+using p_teca_float_array = std::shared_ptr<teca_variant_array_impl<float>>;
+using const_p_teca_float_array = std::shared_ptr<const teca_variant_array_impl<float>>;
+
+using teca_double_array = teca_variant_array_impl<double>;
+using p_teca_double_array = std::shared_ptr<teca_variant_array_impl<double>>;
+using const_p_teca_double_array = std::shared_ptr<const teca_variant_array_impl<double>>;
+
+using teca_char_array = teca_variant_array_impl<char>;
+using p_teca_char_array = std::shared_ptr<teca_variant_array_impl<char>>;
+using const_p_teca_char_array = std::shared_ptr<const teca_variant_array_impl<char>>;
+
+using teca_unsigned_char_array = teca_variant_array_impl<unsigned char>;
+using p_teca_unsigned_char_array = std::shared_ptr<teca_variant_array_impl<unsigned char>>;
+using const_p_teca_unsigned_char_array = std::shared_ptr<const teca_variant_array_impl<unsigned char>>;
+
+using teca_short_array = teca_variant_array_impl<short>;
+using p_teca_short_array = std::shared_ptr<teca_variant_array_impl<short>>;
+using const_p_teca_short_array = std::shared_ptr<const teca_variant_array_impl<short>>;
+
+using teca_unsigned_short_array = teca_variant_array_impl<unsigned short>;
+using p_teca_unsigned_short_array = std::shared_ptr<teca_variant_array_impl<unsigned short>>;
+using const_p_teca_unsigned_short_array = std::shared_ptr<const teca_variant_array_impl<unsigned short>>;
+
+using teca_int_array = teca_variant_array_impl<int>;
+using p_teca_int_array = std::shared_ptr<teca_variant_array_impl<int>>;
+using const_p_teca_int_array = std::shared_ptr<const teca_variant_array_impl<int>>;
+
+using teca_unsigned_int_array = teca_variant_array_impl<unsigned int>;
+using p_teca_unsigned_int_array = std::shared_ptr<teca_variant_array_impl<unsigned int>>;
+using const_p_teca_unsigned_int_array = std::shared_ptr<const teca_variant_array_impl<unsigned int>>;
+
+using teca_long_array = teca_variant_array_impl<long>;
+using p_teca_long_array = std::shared_ptr<teca_variant_array_impl<long>>;
+using const_p_teca_long_array = std::shared_ptr<const teca_variant_array_impl<long>>;
+
+using teca_unsigned_long_array = teca_variant_array_impl<unsigned long>;
+using p_teca_unsigned_long_array = std::shared_ptr<teca_variant_array_impl<unsigned long>>;
+using const_p_teca_unsigned_long_array = std::shared_ptr<const teca_variant_array_impl<unsigned long>>;
+
+using teca_long_long_array = teca_variant_array_impl<long long>;
+using p_teca_long_long_array = std::shared_ptr<teca_variant_array_impl<long long>>;
+using const_p_teca_long_long_array = std::shared_ptr<const teca_variant_array_impl<long long>>;
+
+using teca_unsigned_long_long_array = teca_variant_array_impl<unsigned long long>;
+using p_teca_unsigned_long_long_array = std::shared_ptr<teca_variant_array_impl<unsigned long long>>;
+using const_p_teca_unsigned_long_long_array = std::shared_ptr<const teca_variant_array_impl<unsigned long long>>;
+
+using teca_size_t_array = teca_variant_array_impl<size_t>;
+using p_teca_size_t_array = std::shared_ptr<teca_variant_array_impl<size_t>>;
+using const_p_teca_size_t_array = std::shared_ptr<const teca_variant_array_impl<size_t>>;
+#endif
+
+/** this is a convenience macro to be used to declare a static
+ * New method that will be used to construct new objects in
+ * shared_ptr's. This manages the details of interoperability
+ * with std C++11 shared pointer
+ */
+#define TECA_VARIANT_ARRAY_STATIC_NEW(T, t)                             \
+                                                                        \
+/** Allocate a T<t> */                                                  \
+static std::shared_ptr<T<t>> New()                                      \
+{                                                                       \
+    return std::shared_ptr<T<t>>(new T<t>);                             \
+}                                                                       \
+                                                                        \
+/** Allocate a T<t> of size n */                                        \
+static std::shared_ptr<T<t>> New(size_t n)                              \
+{                                                                       \
+    return std::shared_ptr<T<t>>(new T<t>(n));                          \
+}                                                                       \
+                                                                        \
+/** Allocate a T<t> of size n initialized with v */                     \
+static std::shared_ptr<T<t>> New(size_t n, const t &v)                  \
+{                                                                       \
+    return std::shared_ptr<T<t>>(new T<t>(n, v));                       \
+}                                                                       \
+                                                                        \
+/** Allocate a T<t> initialized with n values from vals */              \
+static std::shared_ptr<T<t>> New(const t *vals, size_t n)               \
+{                                                                       \
+    return std::shared_ptr<T<t>>(new T<t>(vals, n));                    \
+}                                                                       \
+                                                                        \
+using teca_variant_array::shared_from_this;                             \
+                                                                        \
+std::shared_ptr<T> shared_from_this()                                   \
+{                                                                       \
+    return std::static_pointer_cast<T>(shared_from_this());             \
+}                                                                       \
+                                                                        \
+std::shared_ptr<T const> shared_from_this() const                       \
+{                                                                       \
+    return std::static_pointer_cast<T const>(shared_from_this());       \
+}
+
+
+
+
+
+
+
 
 /// @cond
 /// A tag for dispatching operations on POD data
@@ -38,9 +149,8 @@ struct object_dispatch :
 /** Executes the code in body if p is a tt<nt>
  * @param tt     derived container
  * @param nt     contained type
- * @param tt<nt> complete derived type
  * @param p      base class pointer
- * @body         the code to execute if the type matches
+ * @param body   the code to execute if the type matches
  *
  * The following aliases are provided to know the type within the code to execute.
  *
@@ -61,10 +171,9 @@ struct object_dispatch :
  *
  * @param tt     derived container
  * @param nt     contained type
- * @param tt<nt> complete derived type
  * @param p      base class pointer
  * @param i      identifier
- * @body         the code to execute if the type matches
+ * @param body   the code to execute if the type matches
  *
  * The following aliases are provided to know the type within the code to execute.
  *
@@ -409,8 +518,7 @@ template<typename T>
 class teca_variant_array_impl : public teca_variant_array
 {
 public:
-    /** @anchor Constructors
-     * @name Constructors
+    /** @name Array constructors
      * Constructs a new instance containing the templated type.
      */
     ///@{
diff --git a/core/teca_variant_array_fwd.h b/core/teca_variant_array_fwd.h
deleted file mode 100644
index 734f640c5..000000000
--- a/core/teca_variant_array_fwd.h
+++ /dev/null
@@ -1,107 +0,0 @@
-#ifndef teca_variant_array_fwd_h
-#define teca_variant_array_fwd_h
-
-#include <string>
-#include "teca_shared_object.h"
-
-TECA_SHARED_OBJECT_FORWARD_DECL(teca_variant_array)
-TECA_SHARED_OBJECT_TEMPLATE_FORWARD_DECL(teca_variant_array_impl)
-
-#ifndef SWIG
-// convenience defs for POD types
-// these should not be used in API, use teca_variant_array instead
-using teca_string_array = teca_variant_array_impl<std::string>;
-using p_teca_string_array = std::shared_ptr<teca_variant_array_impl<std::string>>;
-using const_p_teca_string_array = std::shared_ptr<const teca_variant_array_impl<std::string>>;
-
-using teca_float_array = teca_variant_array_impl<float>;
-using p_teca_float_array = std::shared_ptr<teca_variant_array_impl<float>>;
-using const_p_teca_float_array = std::shared_ptr<const teca_variant_array_impl<float>>;
-
-using teca_double_array = teca_variant_array_impl<double>;
-using p_teca_double_array = std::shared_ptr<teca_variant_array_impl<double>>;
-using const_p_teca_double_array = std::shared_ptr<const teca_variant_array_impl<double>>;
-
-using teca_char_array = teca_variant_array_impl<char>;
-using p_teca_char_array = std::shared_ptr<teca_variant_array_impl<char>>;
-using const_p_teca_char_array = std::shared_ptr<const teca_variant_array_impl<char>>;
-
-using teca_unsigned_char_array = teca_variant_array_impl<unsigned char>;
-using p_teca_unsigned_char_array = std::shared_ptr<teca_variant_array_impl<unsigned char>>;
-using const_p_teca_unsigned_char_array = std::shared_ptr<const teca_variant_array_impl<unsigned char>>;
-
-using teca_short_array = teca_variant_array_impl<short>;
-using p_teca_short_array = std::shared_ptr<teca_variant_array_impl<short>>;
-using const_p_teca_short_array = std::shared_ptr<const teca_variant_array_impl<short>>;
-
-using teca_unsigned_short_array = teca_variant_array_impl<unsigned short>;
-using p_teca_unsigned_short_array = std::shared_ptr<teca_variant_array_impl<unsigned short>>;
-using const_p_teca_unsigned_short_array = std::shared_ptr<const teca_variant_array_impl<unsigned short>>;
-
-using teca_int_array = teca_variant_array_impl<int>;
-using p_teca_int_array = std::shared_ptr<teca_variant_array_impl<int>>;
-using const_p_teca_int_array = std::shared_ptr<const teca_variant_array_impl<int>>;
-
-using teca_unsigned_int_array = teca_variant_array_impl<unsigned int>;
-using p_teca_unsigned_int_array = std::shared_ptr<teca_variant_array_impl<unsigned int>>;
-using const_p_teca_unsigned_int_array = std::shared_ptr<const teca_variant_array_impl<unsigned int>>;
-
-using teca_long_array = teca_variant_array_impl<long>;
-using p_teca_long_array = std::shared_ptr<teca_variant_array_impl<long>>;
-using const_p_teca_long_array = std::shared_ptr<const teca_variant_array_impl<long>>;
-
-using teca_unsigned_long_array = teca_variant_array_impl<unsigned long>;
-using p_teca_unsigned_long_array = std::shared_ptr<teca_variant_array_impl<unsigned long>>;
-using const_p_teca_unsigned_long_array = std::shared_ptr<const teca_variant_array_impl<unsigned long>>;
-
-using teca_long_long_array = teca_variant_array_impl<long long>;
-using p_teca_long_long_array = std::shared_ptr<teca_variant_array_impl<long long>>;
-using const_p_teca_long_long_array = std::shared_ptr<const teca_variant_array_impl<long long>>;
-
-using teca_unsigned_long_long_array = teca_variant_array_impl<unsigned long long>;
-using p_teca_unsigned_long_long_array = std::shared_ptr<teca_variant_array_impl<unsigned long long>>;
-using const_p_teca_unsigned_long_long_array = std::shared_ptr<const teca_variant_array_impl<unsigned long long>>;
-
-using teca_size_t_array = teca_variant_array_impl<size_t>;
-using p_teca_size_t_array = std::shared_ptr<teca_variant_array_impl<size_t>>;
-using const_p_teca_size_t_array = std::shared_ptr<const teca_variant_array_impl<size_t>>;
-#endif
-
-// this is a convenience macro to be used to declare a static
-// New method that will be used to construct new objects in
-// shared_ptr's. This manages the details of interoperability
-// with std C++11 shared pointer
-#define TECA_VARIANT_ARRAY_STATIC_NEW(T, t)                             \
-                                                                        \
-static std::shared_ptr<T<t>> New()                                      \
-{                                                                       \
-    return std::shared_ptr<T<t>>(new T<t>);                             \
-}                                                                       \
-                                                                        \
-static std::shared_ptr<T<t>> New(size_t n)                              \
-{                                                                       \
-    return std::shared_ptr<T<t>>(new T<t>(n));                          \
-}                                                                       \
-                                                                        \
-static std::shared_ptr<T<t>> New(size_t n, const t &v)                  \
-{                                                                       \
-    return std::shared_ptr<T<t>>(new T<t>(n, v));                       \
-}                                                                       \
-                                                                        \
-static std::shared_ptr<T<t>> New(const t *vals, size_t n)               \
-{                                                                       \
-    return std::shared_ptr<T<t>>(new T<t>(vals, n));                    \
-}                                                                       \
-                                                                        \
-using teca_variant_array::shared_from_this;                             \
-                                                                        \
-std::shared_ptr<T> shared_from_this()                                   \
-{                                                                       \
-    return std::static_pointer_cast<T>(shared_from_this());             \
-}                                                                       \
-                                                                        \
-std::shared_ptr<T const> shared_from_this() const                       \
-{                                                                       \
-    return std::static_pointer_cast<T const>(shared_from_this());       \
-}
-#endif
diff --git a/data/teca_array_attributes.h b/data/teca_array_attributes.h
index d2aaee576..5052da669 100644
--- a/data/teca_array_attributes.h
+++ b/data/teca_array_attributes.h
@@ -8,7 +8,7 @@
 
 /** @brief
  * A convenience container for conventional array attributes necessary and/or
- * useful when producing NetCDF CF format files using the @ref teca_cf_writer.
+ * useful when producing NetCDF CF format files using the teca_cf_writer.
  *
  * @details
  *
diff --git a/data/teca_array_collection.h b/data/teca_array_collection.h
index 322cbfe7b..a2b49e628 100644
--- a/data/teca_array_collection.h
+++ b/data/teca_array_collection.h
@@ -1,115 +1,137 @@
 #ifndef teca_array_collection_h
 #define teca_array_collection_h
 
-#include "teca_array_collection_fwd.h"
+#include "teca_shared_object.h"
 #include "teca_variant_array.h"
 #include <map>
 #include <vector>
 #include <string>
 
+TECA_SHARED_OBJECT_FORWARD_DECL(teca_array_collection)
+
 /// A collection of named arrays.
 class teca_array_collection
 {
 public:
 
-    // construct on heap
+    /// construct on heap
     static
     p_teca_array_collection New()
     { return p_teca_array_collection(new teca_array_collection()); }
 
-    // reset to empty state
+    /// reset to empty state
     void clear();
 
-    // declare a set of arrays. requires name,type pairs
-    // for ex. define("c1",int(),"c2",float()) creates
-    // 2 arrays in the collection the first storing int
-    // the second storing float.
+    /** declare a set of arrays. requires name,type pairs for ex.
+     * define("c1",int(),"c2",float()) creates 2 arrays in the collection the
+     * first storing int the second storing float.
+     */
     template<typename nT, typename aT, typename... oT>
     void declare_set(nT &&a_name, aT a_type, oT &&...args);
 
-    // declare a single array
+    /// declare a single array
     template<typename nT, typename aT>
     void declare(nT &&a_name, aT a_type);
 
-    // add, return the index of the new entry.
-    // or -1 if the array name already exists.
+    /** add, return the index of the new entry,  or -1 if the array name already
+     * exists.
+     */
     int append(p_teca_variant_array array);
+
+    /** add, return the index of the new entry,  or -1 if the array name already
+     * exists.
+     */
     int append(const std::string &name, p_teca_variant_array array);
 
-    // replace the ith array, return 0 on success.
-    // the name of the array is not changed.
+    /** replace the ith array, return 0 on success.  the name of the array is
+     * not changed.
+     */
     int set(unsigned int i, p_teca_variant_array array);
 
-    // add or replace the named array, returns 0 on success.
+    /// add or replace the named array, returns 0 on success.
     int set(const std::string &name, p_teca_variant_array array);
 
-    // remove
+    /// remove the ith array
     int remove(unsigned int i);
+
+    /// remove the named array
     int remove(const std::string &name);
 
-    // number of
+    /// Return the number of arrays
     unsigned int size() const noexcept
     { return m_arrays.size(); }
 
-    // access by id
+    /// access an array by its by id
     p_teca_variant_array get(unsigned int i)
     { return m_arrays[i]; }
 
+    /// access an array by its by id
     const_p_teca_variant_array get(unsigned int i) const
     { return m_arrays[i]; }
 
-    // test for array
+    /// test for array
     bool has(const std::string &name) const;
 
-    // access by name
+    /// access an array by name
     p_teca_variant_array get(const std::string &name);
+
+    /// access an array by name
     const_p_teca_variant_array get(const std::string &name) const;
 
+    /// access an array by name
     p_teca_variant_array operator[](const std::string &name)
     { return this->get(name); }
 
+    /// access an array by name
     const_p_teca_variant_array operator[](const std::string &name) const
     { return this->get(name); }
 
-    // access names
+    // Get the name of the ith array
     std::string &get_name(unsigned int i)
     { return m_names[i]; }
 
+    // Get the name of the ith array
     const std::string &get_name(unsigned int i) const
     { return m_names[i]; }
 
-    // access the list of names
+    // Get the list of names
     std::vector<std::string> &get_names()
     { return m_names; }
 
+    // Get the list of names
     const std::vector<std::string> &get_names() const
     { return m_names; }
 
-    // return a unique string identifier
+    /// Return the name of the class
     std::string get_class_name() const
     { return "teca_array_collection"; }
 
-    // return an integer identifier uniquely naming the dataset type
+    /// return an integer identifier uniquely naming the dataset type
     int get_type_code() const
     { return -1; }
 
-    // copy
+    /// copy
     void copy(const const_p_teca_array_collection &other);
+
+    /// shallow copy
     void shallow_copy(const p_teca_array_collection &other);
 
-    // append
+    /// append
     int append(const const_p_teca_array_collection &other);
+
+    /// shallow append
     int shallow_append(const p_teca_array_collection &other);
 
-    // swap
+    /// swap
     void swap(p_teca_array_collection &other);
 
-    // serialize the data to/from the given stream
-    // for I/O or communication
+    /// serialize the data to the given stream for I/O or communication
     int to_stream(teca_binary_stream &s) const;
+
+    /// serialize the data from the given stream for I/O or communication
     int from_stream(teca_binary_stream &s);
 
-    // stream to/from human readable representation
+    /// stream to a human readable representation
     int to_stream(std::ostream &) const;
 
 protected:
diff --git a/data/teca_array_collection_fwd.h b/data/teca_array_collection_fwd.h
deleted file mode 100644
index d014188c4..000000000
--- a/data/teca_array_collection_fwd.h
+++ /dev/null
@@ -1,8 +0,0 @@
-#ifndef teca_array_collection_fwd_h
-#define teca_array_collection_fwd_h
-
-#include "teca_shared_object.h"
-
-TECA_SHARED_OBJECT_FORWARD_DECL(teca_array_collection)
-
-#endif
diff --git a/data/teca_calendar_util.h b/data/teca_calendar_util.h
index 217bde06f..5d8255ad9 100644
--- a/data/teca_calendar_util.h
+++ b/data/teca_calendar_util.h
@@ -3,7 +3,7 @@
 
 /// @file
 
-#include "teca_variant_array_fwd.h"
+#include "teca_variant_array.h"
 #include "teca_metadata.h"
 
 #include <string>
@@ -15,8 +15,7 @@
 namespace teca_calendar_util
 {
 
-/** @anchor Gregorian calendar
- * @name Gregorian calendar
+/** @name Gregorian calendar
  * functions for date computations in gregorian calendar.  to use convert the
  * origin to a gergorian_number do the calculation and convert the number back
  * into a date useing date_from_gregorian_number. for details about the math
@@ -133,8 +132,8 @@ class interval_iterator
     /** Initialize the iterator from a metadata object following the
      * conventions defined by the teca_cf_reader.
      * @param[in] md a metadata object
-     * @param[in] the first step to include in the series or 0 to use all
-     * @param[in] the last step to include in the series or -1 to use all
+     * @param[in] first_step the first step to include in the series or 0 to use all
+     * @param[in] last_step the last step to include in the series or -1 to use all
      * @returns 0 if successfully initialized
      */
     virtual int initialize(const teca_metadata &md,
@@ -144,8 +143,8 @@ class interval_iterator
      * @param[in] t  An array of time values
      * @param[in] units A string units of the time values
      * @param[in] calendar A string name of the calendar system
-     * @param[in] the first step to include in the series or 0 to use all
-     * @param[in] the last step to include in the series or -1 to use all
+     * @param[in] first_step the first step to include in the series or 0 to use all
+     * @param[in] last_step the last step to include in the series or -1 to use all
      * @returns 0 if successfully initialized
      */
     virtual int initialize(const const_p_teca_variant_array &t,
@@ -206,6 +205,8 @@ class season_iterator : public interval_iterator
      * @param[in] t  An array of time values
      * @param[in] units A string units of the time values
      * @param[in] calendar A string name of the calendar system
+     * @param[in] first_step the first step to include in the series or 0 to use all
+     * @param[in] last_step the last step to include in the series or -1 to use all
      * @returns 0 if successfully initialized
      */
     int initialize(const const_p_teca_variant_array &t,
@@ -259,6 +260,8 @@ class year_iterator : public interval_iterator
      * @param[in] t  An array of time values
      * @param[in] units A string units of the time values
      * @param[in] calendar A string name of the calendar system
+     * @param[in] first_step the first step to include in the series or 0 to use all
+     * @param[in] last_step the last step to include in the series or -1 to use all
      * @returns 0 if successfully initialized
      */
     int initialize(const const_p_teca_variant_array &t,
@@ -293,6 +296,8 @@ class month_iterator : public interval_iterator
      * @param[in] t  An array of time values
      * @param[in] units A string units of the time values
      * @param[in] calendar A string name of the calendar system
+     * @param[in] first_step the first step to include in the series or 0 to use all
+     * @param[in] last_step the last step to include in the series or -1 to use all
      * @returns 0 if successfully initialized
      */
     int initialize(const const_p_teca_variant_array &t,
@@ -328,6 +333,8 @@ class day_iterator : public interval_iterator
      * @param[in] t  An array of time values
      * @param[in] units A string units of the time values
      * @param[in] calendar A string name of the calendar system
+     * @param[in] first_step the first step to include in the series or 0 to use all
+     * @param[in] last_step the last step to include in the series or -1 to use all
      * @returns 0 if successfully initialized
      */
     int initialize(const const_p_teca_variant_array &t,
@@ -349,12 +356,13 @@ class day_iterator : public interval_iterator
 
 using p_interval_iterator = std::shared_ptr<interval_iterator>;
 
+/// A factory for interval_iterator
 class interval_iterator_factory
 {
 public:
     /** Allocate and return an instance of the named iterator
-     * @param[in] Name of the desired interval iterator. One of daily, monthly,
-     *            seasonal, or yearly
+     * @param[in] interval Name of the desired interval iterator. One of daily,
+     *                     monthly, seasonal, or yearly
      * @returns an instance of interval_iterator
      */
     static p_interval_iterator New(const std::string &interval);
@@ -363,14 +371,13 @@ class interval_iterator_factory
     enum {invalid = 0, daily = 2, monthly = 3, seasonal = 4, yearly = 5};
 
     /** Allocate and return an instance of the named iterator
-     * @param[in] Name of the desired interval iterator. One of daily, monthly,
-     *            seasonal, or yearly
+     * @param[in] interval Id of the desired interval iterator. One of daily,
+     *            monthly, seasonal, or yearly
      * @returns an instance of interval_iterator
      */
     static p_interval_iterator New(int interval);
 };
 
-
 }
 
 /// send the time_point to a stream in humnan readable form
diff --git a/data/teca_coordinate_util.h b/data/teca_coordinate_util.h
index 7110229ed..01fb8d0fb 100644
--- a/data/teca_coordinate_util.h
+++ b/data/teca_coordinate_util.h
@@ -37,7 +37,7 @@ template <typename n_t>
 struct equal_tt {};
 
 #define declare_equal_tt(cpp_t, atol, rtol)                                 \
-/** Specialization for cpp_t with default absTol=atol and reltol=rtol */    \
+/** Specialization for cpp_t with default absTol and relTol */              \
 template <>                                                                 \
 struct equal_tt<cpp_t>                                                      \
 {                                                                           \
diff --git a/data/teca_database.h b/data/teca_database.h
index 97e06f2ba..11df3a08c 100644
--- a/data/teca_database.h
+++ b/data/teca_database.h
@@ -3,11 +3,13 @@
 
 #include "teca_dataset.h"
 #include "teca_table.h"
-#include "teca_database_fwd.h"
+#include "teca_shared_object.h"
 #include "teca_table_collection.h"
 #include <iosfwd>
 class teca_binary_stream;
 
+TECA_SHARED_OBJECT_FORWARD_DECL(teca_database)
+
 /// A collection of named tables.
 /**
  * A dataset consisting of a collection of named tables. This
diff --git a/data/teca_database_fwd.h b/data/teca_database_fwd.h
deleted file mode 100644
index e8f784964..000000000
--- a/data/teca_database_fwd.h
+++ /dev/null
@@ -1,7 +0,0 @@
-#ifndef teca_database_fwd_h
-#define teca_database_fwd_h
-
-#include "teca_shared_object.h"
-TECA_SHARED_OBJECT_FORWARD_DECL(teca_database)
-
-#endif
diff --git a/data/teca_mesh.h b/data/teca_mesh.h
index 567abbb49..8196fcf29 100644
--- a/data/teca_mesh.h
+++ b/data/teca_mesh.h
@@ -1,10 +1,12 @@
 #ifndef teca_mesh_h
 #define teca_mesh_h
 
-#include "teca_mesh_fwd.h"
 #include "teca_dataset.h"
 #include "teca_metadata.h"
 #include "teca_array_collection.h"
+#include "teca_shared_object.h"
+
+TECA_SHARED_OBJECT_FORWARD_DECL(teca_mesh)
 
 /// A base class for geometric data.
 /**
diff --git a/data/teca_mesh_fwd.h b/data/teca_mesh_fwd.h
deleted file mode 100644
index 92b2b3aa0..000000000
--- a/data/teca_mesh_fwd.h
+++ /dev/null
@@ -1,8 +0,0 @@
-#ifndef teca_mesh_fwd_h
-#define teca_mesh_fwd_h
-
-#include "teca_shared_object.h"
-
-TECA_SHARED_OBJECT_FORWARD_DECL(teca_mesh)
-
-#endif
diff --git a/data/teca_table_collection.h b/data/teca_table_collection.h
index f6d7aa254..1bc2a4a68 100644
--- a/data/teca_table_collection.h
+++ b/data/teca_table_collection.h
@@ -1,12 +1,15 @@
 #ifndef teca_table_collection_h
 #define teca_table_collection_h
 
-#include "teca_table_collection_fwd.h"
 #include "teca_table.h"
+#include "teca_shared_object.h"
+
 #include <map>
 #include <vector>
 #include <string>
 
+TECA_SHARED_OBJECT_FORWARD_DECL(teca_table_collection)
+
 /// A collection of named tables.
 class teca_table_collection
 {
diff --git a/data/teca_table_collection_fwd.h b/data/teca_table_collection_fwd.h
deleted file mode 100644
index 732902648..000000000
--- a/data/teca_table_collection_fwd.h
+++ /dev/null
@@ -1,8 +0,0 @@
-#ifndef teca_table_collection_fwd_h
-#define teca_table_collection_fwd_h
-
-#include "teca_shared_object.h"
-
-TECA_SHARED_OBJECT_FORWARD_DECL(teca_table_collection)
-
-#endif
diff --git a/data/teca_uniform_cartesian_mesh.h b/data/teca_uniform_cartesian_mesh.h
index 19baec0e6..f6e31c66c 100644
--- a/data/teca_uniform_cartesian_mesh.h
+++ b/data/teca_uniform_cartesian_mesh.h
@@ -1,8 +1,10 @@
 #ifndef teca_uniform_cartesian_mesh_h
 #define teca_uniform_cartesian_mesh_h
 
-#include "teca_uniform_cartesian_mesh_fwd.h"
 #include "teca_mesh.h"
+#include "teca_shared_object.h"
+
+TECA_SHARED_OBJECT_FORWARD_DECL(teca_uniform_cartesian_mesh)
 
 /// Data on a uniform cartesian mesh.
 class teca_uniform_cartesian_mesh : public teca_mesh
@@ -22,19 +24,19 @@ class teca_uniform_cartesian_mesh : public teca_mesh
     TECA_DATASET_METADATA(extent, unsigned long, 6)
     TECA_DATASET_METADATA(local_extent, unsigned long, 6)
 
-    // return a unique string identifier
+    /// return a unique string identifier
     std::string get_class_name() const override
     { return "teca_uniform_cartesian_mesh"; }
 
-    // return a unique integer identifier
+    /// return a unique integer identifier
     int get_type_code() const override;
 
-    // copy data and metadata. shallow copy uses reference
-    // counting, while copy duplicates the data.
+    /// copy data and metadata. shallow copy uses reference
+    /// counting, while copy duplicates the data.
     void copy(const const_p_teca_dataset &) override;
     void shallow_copy(const p_teca_dataset &) override;
 
-    // swap internals of the two objects
+    /// swap internals of the two objects
     void swap(p_teca_dataset &) override;
 
 protected:
diff --git a/data/teca_uniform_cartesian_mesh_fwd.h b/data/teca_uniform_cartesian_mesh_fwd.h
deleted file mode 100644
index 79a66e960..000000000
--- a/data/teca_uniform_cartesian_mesh_fwd.h
+++ /dev/null
@@ -1,8 +0,0 @@
-#ifndef teca_uniform_cartesian_mesh_fwd_h
-#define teca_uniform_cartesian_mesh_fwd_h
-
-#include "teca_shared_object.h"
-
-TECA_SHARED_OBJECT_FORWARD_DECL(teca_uniform_cartesian_mesh)
-
-#endif
diff --git a/io/teca_cartesian_mesh_reader_factory.h b/io/teca_cartesian_mesh_reader_factory.h
index 40a1bc4e1..862a8091c 100644
--- a/io/teca_cartesian_mesh_reader_factory.h
+++ b/io/teca_cartesian_mesh_reader_factory.h
@@ -1,21 +1,25 @@
 #ifndef teca_cartesian_mesh_reader_factory_h
 #define teca_cartesian_mesh_reader_factory_h
 
+/// @file
+
 #include "teca_algorithm.h"
 
+/// A factory for Cartesian mesh readers
 struct teca_cartesian_mesh_reader_factory
 {
-    // creates and initialized a reader from a given file name
-    // or regular expression.  the file extension is examined,
-    // to determine the type of reader to create. the supported
-    // extentsions and the associated readers are as follows:
-    //
-    // bin -- teca_cartesian_mesh_reader
-    // nc  -- teca_cf_reader
-    // mcf -- teca_multi_cf_reader
-    //
-    // returns a new instance of the reader with the file or
-    // regex set or a nullptr if an error is encountered
+    /** creates and initialized a reader from a given file name or regular
+     * expression.  the file extension is examined, to determine the type of
+     * reader to create. the supported extentsions and the associated readers
+     * are as follows:
+     *
+     *      bin -- teca_cartesian_mesh_reader
+     *      nc  -- teca_cf_reader
+     *      mcf -- teca_multi_cf_reader
+     *
+     * returns a new instance of the reader with the file or regex set or a
+     * nullptr if an error is encountered
+     */
     static p_teca_algorithm New(const std::string &file);
 };
 
diff --git a/io/teca_cartesian_mesh_writer_factory.h b/io/teca_cartesian_mesh_writer_factory.h
index 8a3c70034..c76decc0d 100644
--- a/io/teca_cartesian_mesh_writer_factory.h
+++ b/io/teca_cartesian_mesh_writer_factory.h
@@ -3,18 +3,20 @@
 
 #include "teca_algorithm.h"
 
+/// A factory for Cartesian mesh writers
 struct teca_cartesian_mesh_writer_factory
 {
-    // creates and initialized a writer from a given file name
-    // or regular expression.  the file extension is examined,
-    // to determine the type of writer to create. the supported
-    // extentsions and the associated writers are as follows:
-    //
-    // bin -- teca_cartesian_mesh_writer
-    // nc  -- teca_cf_writer
-    //
-    // returns a new instance of the writer with the file or
-    // regex set or a nullptr if an error is encountered
+     /** creates and initialized a writer from a given file name
+      * or regular expression.  the file extension is examined,
+      * to determine the type of writer to create. the supported
+      * extentsions and the associated writers are as follows:
+      *
+      * bin -- teca_cartesian_mesh_writer
+      * nc  -- teca_cf_writer
+      *
+      * returns a new instance of the writer with the file or
+      * regex set or a nullptr if an error is encountered
+      */
     static p_teca_algorithm New(const std::string &file);
 };
 
diff --git a/io/teca_cf_reader.h b/io/teca_cf_reader.h
index 9c1e0752b..0ea51aecb 100644
--- a/io/teca_cf_reader.h
+++ b/io/teca_cf_reader.h
@@ -36,7 +36,7 @@ using p_teca_cf_reader_internals = std::shared_ptr<teca_cf_reader_internals>;
  *
  *  | key             | description |
  *  | ----            | ----------- |
- *  | <variable name> | a metadata object holding all NetCDF attributes, and |
+ *  | [variable name] | a metadata object holding all NetCDF attributes, and |
  *  |                 | TECA specific per-array metadata |
  *
  * ### cooridnate metadata:
@@ -78,8 +78,7 @@ class teca_cf_reader : public teca_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    /** @anchor file_name
-     * @name file_name
+    /** @name file_name
      * Set a list of files to open. If this is used then the files_regex is
      * ignored.
      */
@@ -87,8 +86,7 @@ class teca_cf_reader : public teca_algorithm
     TECA_ALGORITHM_VECTOR_PROPERTY(std::string, file_name)
     ///@}
 
-    /** @anchor files_regex
-     * @name files_regex
+    /** @name files_regex
      * Set a regular expression identifying the set of files comprising the
      * dataset. This should contain the full path to the files and the regular
      * expression.  Only the final component of a path may contain a regex.
@@ -101,32 +99,28 @@ class teca_cf_reader : public teca_algorithm
     TECA_ALGORITHM_PROPERTY(std::string, files_regex)
     ///@}
 
-    /** @anchor periodic_in_x
-     * @name periodic_in_x
+    /** @name periodic_in_x
      * A flag that indicates a periodic bondary in the z direction
      */
     ///@{
     TECA_ALGORITHM_PROPERTY(int, periodic_in_x)
     ///@}
 
-    /** @anchor periodic_in_y
-     * @name periodic_in_y
+    /** @name periodic_in_y
      * A flag that indicates a periodic bondary in the z direction
      */
     ///@{
     TECA_ALGORITHM_PROPERTY(int, periodic_in_y)
     ///@}
 
-    /** @anchor periodic_in_z
-     * @name periodic_in_z
+    /** @name periodic_in_z
      * A flag that indicates a periodic bondary in the z direction
      */
     ///@{
     TECA_ALGORITHM_PROPERTY(int, periodic_in_z)
     ///@}
 
-    /** @anchor x_axis_variable
-     * @name x_axis_variable
+    /** @name x_axis_variable
      * Set the name of the variable to use for the x coordinate axis.
      * An empty string disables this dimension.
      */
@@ -134,16 +128,14 @@ class teca_cf_reader : public teca_algorithm
     TECA_ALGORITHM_PROPERTY(std::string, x_axis_variable)
     ///@}
 
-    /** @anchor y_axis_variable
-     * @name y_axis_variable
+    /** @name y_axis_variable
      * Set the name of the variable to use for the y coordinate axis.
      * An empty string disables this dimension.
      */
     ///@{
     TECA_ALGORITHM_PROPERTY(std::string, y_axis_variable)
     ///@}
-    /** @anchor z_axis_variable
-     * @name z_axis_variable
+    /** @name z_axis_variable
      * Set the name of the variable to use for the z coordinate axis.
      * An empty string disables this dimension.
      */
@@ -151,8 +143,7 @@ class teca_cf_reader : public teca_algorithm
     TECA_ALGORITHM_PROPERTY(std::string, z_axis_variable)
     ///@}
 
-    /** @anchor t_axis_variable
-     * @name t_axis_variable
+    /** @name t_axis_variable
      * Set the name of the variable to use for the t coordinate axis.
      * An empty string disables this dimension.
      */
@@ -160,8 +151,7 @@ class teca_cf_reader : public teca_algorithm
     TECA_ALGORITHM_PROPERTY(std::string, t_axis_variable)
     ///@}
 
-    /** @anchor calendar
-     * @name calendar
+    /** @name calendar
      * Override the calendar.  When specified the values takes precedence over
      * the values found in the file.
      */
@@ -169,8 +159,7 @@ class teca_cf_reader : public teca_algorithm
     TECA_ALGORITHM_PROPERTY(std::string, calendar)
     ///@}
 
-    /** @anchor t_units
-     * @name t_units
+    /** @name t_units
      * Override the time units. When specified the value takes precedence over
      * the values found in the file.
      */
@@ -178,8 +167,7 @@ class teca_cf_reader : public teca_algorithm
     TECA_ALGORITHM_PROPERTY(std::string, t_units)
     ///@}
 
-    /** @anchor filename_time_template
-     * @name filename_time_template
+    /** @name filename_time_template
      * a way to infer time from the filename if the time axis is not stored in
      * the file itself. std::get_time format codes are used.  If a calendar is
      * not specified then the standard calendar is used. If time units are not
@@ -201,8 +189,7 @@ class teca_cf_reader : public teca_algorithm
     TECA_ALGORITHM_PROPERTY(std::string, filename_time_template)
     ///@}
 
-    /** @anchor t_value
-     * @name t_value
+    /** @name t_value
      * an explicit list of double precision time values to use.  set
      * t_axis_variable to an empty string to use.
      */
@@ -210,8 +197,7 @@ class teca_cf_reader : public teca_algorithm
     TECA_ALGORITHM_VECTOR_PROPERTY(double, t_value)
     ///@}
 
-    /** @anchor max_metadata_ranks
-     * @name max_metadata_ranks
+    /** @name max_metadata_ranks
      * set/get the number of ranks used to read the time axis.  the default
      * value of 1024 ranks works well on NERSC Cori scratch file system and may
      * not be optimal on other systems.
@@ -220,8 +206,7 @@ class teca_cf_reader : public teca_algorithm
     TECA_ALGORITHM_PROPERTY(int, max_metadata_ranks)
     ///@}
 
-    /** @anchor clamp_dimensions_of_one
-     * @name clamp_dimensions_of_one
+    /** @name clamp_dimensions_of_one
      * If set the requested extent will be clamped in a given direction if the
      * coorinate axis in that dircetion has a length of 1 and the requested extent
      * would be out of bounds. This exists to deal with non-conformant data and
diff --git a/io/teca_cf_time_axis_data_reduce.h b/io/teca_cf_time_axis_data_reduce.h
index 258980d9d..ff51dbe15 100644
--- a/io/teca_cf_time_axis_data_reduce.h
+++ b/io/teca_cf_time_axis_data_reduce.h
@@ -2,7 +2,7 @@
 #define teca_cf_time_axis_data_reduce_h
 
 #include "teca_shared_object.h"
-#include "teca_dataset_fwd.h"
+#include "teca_dataset.h"
 #include "teca_metadata.h"
 #include "teca_index_reduce.h"
 
diff --git a/io/teca_cf_writer.h b/io/teca_cf_writer.h
index 8d8ebd505..61e9d98fd 100644
--- a/io/teca_cf_writer.h
+++ b/io/teca_cf_writer.h
@@ -83,8 +83,7 @@ class teca_cf_writer : public teca_threaded_algorithm
     TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
     TECA_SET_ALGORITHM_PROPERTIES()
 
-    /** @anchor file_name
-     * @name file_name
+    /** @name file_name
      * Set the output filename. For time series the substring %t% is replaced
      * with the current time step or date. See comments on date_format below
      * for info about date formatting.
@@ -94,8 +93,7 @@ class teca_cf_writer : public teca_threaded_algorithm
     ///@}
 
 
-    /** @anchor date_format
-     * @name date_format
+    /** @name date_format
      * set the format for the date to write in the filename. this requires the
      * input dataset to have unit/calendar information if none are available,
      * the time index is used instead. (%F-%HZ)
@@ -104,30 +102,27 @@ class teca_cf_writer : public teca_threaded_algorithm
     TECA_ALGORITHM_PROPERTY(std::string, date_format)
     ///@}
 
-    /** @anchor first_step
-     * @name first_step
+    /** @name first_step
      * Set the first step in the range of time step to process.
      */
     ///@{
     TECA_ALGORITHM_PROPERTY(long, first_step)
     ///@}
 
-    /** @anchor last_step
-     * @name last_step
+    /** @name last_step
      * Set the last step in the range of time step to process.
      */
     ///@{
     TECA_ALGORITHM_PROPERTY(long, last_step)
     ///@}
 
-    /** @anchor layout
-     * @name layout
+    /** @name layout
      * Set the layout mode to one of : number_of_steps, daily, monthly,
      * seasonal, or yearly. This controls the size of the files written.  In
      * daily, monthly, seasonal, and yearly modes each file will contain the
      * steps spanning the given duration. The number_of_steps mode writes a
      * fixed number of steps per file which can be set using the
-     * @ref steps_per_file property.
+     * steps_per_file property.
      */
     ///@{
     enum {invalid=0, number_of_steps=1, daily=2, monthly=3, seasonal=4, yearly=5};
@@ -154,8 +149,7 @@ class teca_cf_writer : public teca_threaded_algorithm
     }
     ///@}
 
-    /** @anchor steps_per_file
-     * @name steps_per_file
+    /** @name steps_per_file
      * Set how many time steps are written to each file when the layout mode is
      * set to number_of_steps.
      */
@@ -163,8 +157,7 @@ class teca_cf_writer : public teca_threaded_algorithm
     TECA_ALGORITHM_PROPERTY(unsigned int, steps_per_file)
     ///@}
 
-    /** @anchor mode_flags
-     * @name mode_flags
+    /** @name mode_flags
      * sets the flags passed to NetCDF during file creation. (NC_CLOBBER)
      */
     ///@{
@@ -172,8 +165,7 @@ class teca_cf_writer : public teca_threaded_algorithm
     ///@}
 
 
-    /** @anchor use_unlimited_dim
-     * @name use_unlimited_dim
+    /** @name use_unlimited_dim
      * if set the slowest varying dimension is specified to be NC_UNLIMITED.
      * This has a negative impact on performance when reading the values in a
      * single pass. However, unlimited dimensions are used ubiquitously thus
@@ -186,8 +178,7 @@ class teca_cf_writer : public teca_threaded_algorithm
     TECA_ALGORITHM_PROPERTY(int, use_unlimited_dim)
     ///@}
 
-    /** @anchor compression_level
-     * @name compression_level
+    /** @name compression_level
      * sets the compression level used for each variable compression is not
      * used if the value is less than or equal to 0. This feature requires
      * collective writes and is incompatible with out of order execution,
@@ -197,8 +188,7 @@ class teca_cf_writer : public teca_threaded_algorithm
     TECA_ALGORITHM_PROPERTY(int, compression_level)
     ///@}
 
-    /** @anchor flush_files
-     * @name flush_files
+    /** @name flush_files
      * Flush files before closing them, this may be necessary if accessing data
      * immediately.
      */
@@ -207,8 +197,7 @@ class teca_cf_writer : public teca_threaded_algorithm
     ///@}
 ;
 
-    /** @anchor point_array
-     * @name point_array
+    /** @name point_array
      * Specify the arrays to write. A data array is only written to disk if
      * it is included in this list. It is an error to not specify at least
      * one point centered array to write
@@ -217,8 +206,7 @@ class teca_cf_writer : public teca_threaded_algorithm
     TECA_ALGORITHM_VECTOR_PROPERTY(std::string, point_array)
     ///@}
 
-    /** @anchor information_array
-     * @name information_array
+    /** @name information_array
      * Set the list of non-geometric arrays to write.
      */
     ///@{
diff --git a/io/teca_multi_cf_reader.h b/io/teca_multi_cf_reader.h
index 34f9ecec9..84804782e 100644
--- a/io/teca_multi_cf_reader.h
+++ b/io/teca_multi_cf_reader.h
@@ -6,7 +6,6 @@
 #include "teca_shared_object.h"
 #include "teca_cf_reader.h"
 
-
 #include <set>
 #include <vector>
 #include <string>
@@ -111,8 +110,7 @@ class teca_multi_cf_reader : public teca_algorithm
     /// get the list of variables that the reader will serve up
     void get_variables(std::vector<std::string> &vars);
 
-    /** @anchor periodic_in_x
-     * @name periodic_in_x
+    /** @name periodic_in_x
      * Set to indicate the presence of a periodic boundary in the x direction.
      * If set this will override the corresponding setting from the MCF file
      * for all internal readers.
@@ -122,8 +120,7 @@ class teca_multi_cf_reader : public teca_algorithm
     int get_periodic_in_x() const;
     ///@}
 
-    /** @anchor x_axis_variable_
-     * @name x_axis_variable
+    /** @name x_axis_variable
      * Set the variable to use for the mesh x-axis. If set this will override
      * the corresponding setting from the MCF file for all internal readers.
      */
@@ -132,8 +129,7 @@ class teca_multi_cf_reader : public teca_algorithm
     std::string get_x_axis_variable() const;
     ///@}
 
-    /** @anchor y_axis_variable_
-     * @name y_axis_variable
+    /** @name y_axis_variable
      * Set the variable to use for the mesh y-axis. If set this will override
      * the corresponding setting from the MCF file for all internal readers.
      */
@@ -142,8 +138,7 @@ class teca_multi_cf_reader : public teca_algorithm
     std::string get_y_axis_variable() const;
     ///@}
 
-    /** @anchor z_axis_variable_
-     * @name z_axis_variable
+    /** @name z_axis_variable
      * Set the variable to use for the mesh z-axis. Leaving the z-axis empty
      * results in a 2D mesh. You must set this to the correct vertical
      * coordinate dimension to produce a 3D mesh. If set this will override
@@ -154,8 +149,7 @@ class teca_multi_cf_reader : public teca_algorithm
     std::string get_z_axis_variable() const;
     ///@}
 
-    /** @anchor t_axis_variable_
-     * @name t_axis_variable
+    /** @name t_axis_variable_
      * Set the variable to use for the mesh t-axis. Default "time". Setting
      * this to an empty string disables the time axis. If set this will
      * override the corresponding setting from the MCF file for all internal
@@ -166,8 +160,7 @@ class teca_multi_cf_reader : public teca_algorithm
     std::string get_t_axis_variable() const;
     ///@}
 
-    /** @anchor calendar
-     * @name calendar
+    /** @name calendar
      * Use this to override the calendar, or set one when specifying t_values
      * directly. If set this will override the corresponding setting from the
      * MCF file for all internal readers.
@@ -177,8 +170,7 @@ class teca_multi_cf_reader : public teca_algorithm
     std::string get_calendar() const;
     ///@}
 
-    /** @anchor t_units
-     * @name t_units
+    /** @name t_units
      * Use this to set or override the time units. This is necessary when
      * specifying time values directly. If set this will override the
      * corresponding setting from the MCF file for all internal readers.
@@ -188,8 +180,7 @@ class teca_multi_cf_reader : public teca_algorithm
     std::string get_t_units() const;
     ///@}
 
-    /** @anchor filename_time_template
-     * @name filename_time_template
+    /** @name filename_time_template
      * a way to infer time from the filename if the time axis is not stored in
      * the file itself. If set this will override the corresponding setting
      * from the MCF file for all internal readers.
@@ -210,8 +201,7 @@ class teca_multi_cf_reader : public teca_algorithm
     std::string get_filename_time_template() const;
     ///@}
 
-    /** @anchor t_values
-     * @name t_values
+    /** @name t_values
      * Set the time values to use instead if a time variable doesn't exist or
      * you need to override it. If set this will override the corresponding
      * setting from the MCF file for all internal readers.
@@ -220,8 +210,7 @@ class teca_multi_cf_reader : public teca_algorithm
     TECA_ALGORITHM_VECTOR_PROPERTY(double, t_value)
     ///@}
 
-    /** @anchor max_metadata_ranks
-     * @name max_metadata_ranks
+    /** @name max_metadata_ranks
      * set/get the number of ranks used to read the time axis. If set this
      * will override the corresponding setting from the MCF file for all
      * internal readers.
@@ -230,8 +219,7 @@ class teca_multi_cf_reader : public teca_algorithm
     TECA_ALGORITHM_PROPERTY(int, max_metadata_ranks)
     ///@}
 
-    /** @anchor periodic_in_x
-     * @name periodic_in_x
+    /** @name periodic_in_x
      * Set to indicate the presence of a periodic boundary in the x direction.
      * If set this will override the corresponding setting from the MCF file
      * for all internal readers.
@@ -239,8 +227,7 @@ class teca_multi_cf_reader : public teca_algorithm
     ///@{
     ///@}
 
-    /** @anchor clamp_dimensions_of_one
-     * @name clamp_dimensions_of_one
+    /** @name clamp_dimensions_of_one
      * If set the requested extent will be clamped in a given direction if the
      * coorinate axis in that direction has a length of 1 and the requested
      * extent would be out of bounds. This is a work around to enable loading
diff --git a/io/teca_wrf_reader.h b/io/teca_wrf_reader.h
index 7ac3a3c40..292e2bae9 100644
--- a/io/teca_wrf_reader.h
+++ b/io/teca_wrf_reader.h
@@ -23,8 +23,8 @@ using p_teca_wrf_reader_internals = std::shared_ptr<teca_wrf_reader_internals>;
  *  | key                   | description |
  *  | ----                  | ----------- |
  *  | variables             | a list of all available variables |
- *  | <var>                 | a metadata object holding all NetCDF attributes for the |
- *  |                       | variable named <var> |
+ *  | [var]                 | a metadata object holding all NetCDF attributes for the |
+ *  |                       | variable named [var] |
  *  | time variables        | a list of all variables with time as the only |
  *  |                       | dimension |
  *  | coordinates           | a metadata object holding names and arrays of the |
diff --git a/python/teca_py_algorithm.h b/python/teca_py_algorithm.h
index 58dcf51dc..cfc326d67 100644
--- a/python/teca_py_algorithm.h
+++ b/python/teca_py_algorithm.h
@@ -12,11 +12,9 @@
 #include <Python.h>
 #include <vector>
 
-
-/// Reports an error from a user provided callback.
-/** We are going to be overly verbose in an effort to help
- * the user debug their code. package this up for use in all
- * the callbacks.
+/** Reports an error from a user provided callback.  We are going to be overly
+ * verbose in an effort to help the user debug their code. package this up for
+ * use in all the callbacks.
  */
 #define TECA_PY_CALLBACK_ERROR(_phase, _cb_obj)             \
     {                                                       \
diff --git a/python/teca_py_core.i b/python/teca_py_core.i
index 20dc6843a..8348021f8 100644
--- a/python/teca_py_core.i
+++ b/python/teca_py_core.i
@@ -158,7 +158,6 @@ class teca_variant_array;
 %ignore operator<<(std::ostream &, const std::vector<std::string> &);
 %include "teca_common.h"
 %include "teca_shared_object.h"
-%include "teca_variant_array_fwd.h"
 %ignore teca_variant_array::operator=;
 %ignore teca_variant_array_factory;
 %ignore teca_variant_array::append(const teca_variant_array &other);
@@ -484,7 +483,6 @@ class teca_dataset;
 %template(teca_dataset_base) std::enable_shared_from_this<teca_dataset>;
 %ignore teca_dataset::operator=;
 %ignore teca_dataset::set_index_request_key(std::string const *);
-%include "teca_dataset_fwd.h"
 %include "teca_dataset.h"
 TECA_PY_CONST_CAST(teca_dataset)
 %extend teca_dataset
@@ -589,7 +587,6 @@ class teca_algorithm_executive;
 %ignore teca_algorithm_executive::operator=;
 %include "teca_common.h"
 %include "teca_shared_object.h"
-%include "teca_algorithm_executive_fwd.h"
 %include "teca_algorithm_executive.h"
 
 /***************************************************************************
@@ -613,7 +610,6 @@ typedef std::pair<std::shared_ptr<teca_algorithm>, unsigned int> teca_algorithm_
 %template(teca_output_port_type) std::pair<std::shared_ptr<teca_algorithm>, unsigned int>;
 %include "teca_common.h"
 %include "teca_shared_object.h"
-%include "teca_algorithm_fwd.h"
 %include "teca_program_options.h"
 %include "teca_algorithm.h"
 
@@ -707,7 +703,6 @@ typedef std::pair<std::shared_ptr<teca_algorithm>, unsigned int> teca_algorithm_
 %ignore teca_threaded_algorithm::shared_from_this;
 %shared_ptr(teca_threaded_algorithm)
 %ignore teca_threaded_algorithm::operator=;
-%include "teca_threaded_algorithm_fwd.h"
 %include "teca_threaded_algorithm.h"
 
 /***************************************************************************
@@ -716,7 +711,6 @@ typedef std::pair<std::shared_ptr<teca_algorithm>, unsigned int> teca_algorithm_
 %ignore teca_index_reduce::shared_from_this;
 %shared_ptr(teca_index_reduce)
 %ignore teca_index_reduce::operator=;
-%include "teca_index_reduce_fwd.h"
 %include "teca_index_reduce.h"
 
 /***************************************************************************
@@ -754,7 +748,6 @@ typedef std::pair<std::shared_ptr<teca_algorithm>, unsigned int> teca_algorithm_
 %ignore teca_programmable_algorithm::get_request_callback;
 %ignore teca_programmable_algorithm::set_execute_callback;
 %ignore teca_programmable_algorithm::get_execute_callback;
-%include "teca_programmable_algorithm_fwd.h"
 %include "teca_programmable_algorithm.h"
 
 /***************************************************************************
@@ -792,7 +785,6 @@ typedef std::pair<std::shared_ptr<teca_algorithm>, unsigned int> teca_algorithm_
 %ignore teca_threaded_programmable_algorithm::get_request_callback;
 %ignore teca_threaded_programmable_algorithm::set_execute_callback;
 %ignore teca_threaded_programmable_algorithm::get_execute_callback;
-%include "teca_programmable_algorithm_fwd.h"
 %include "teca_threaded_programmable_algorithm.h"
 
 /***************************************************************************
@@ -839,7 +831,6 @@ typedef std::pair<std::shared_ptr<teca_algorithm>, unsigned int> teca_algorithm_
 %ignore teca_programmable_reduce::get_reduce_callback;
 %ignore teca_programmable_reduce::set_finalize_callback;
 %ignore teca_programmable_reduce::get_finalize_callback;
-%include "teca_programmable_reduce_fwd.h"
 %include "teca_programmable_reduce.h"
 
 /***************************************************************************
diff --git a/python/teca_py_data.i b/python/teca_py_data.i
index e99b3466f..e5a139b7a 100644
--- a/python/teca_py_data.i
+++ b/python/teca_py_data.i
@@ -77,7 +77,6 @@
 %shared_ptr(teca_array_collection)
 %ignore teca_array_collection::operator=;
 %ignore teca_array_collection::operator[];
-%include "teca_array_collection_fwd.h"
 %include "teca_array_collection.h"
 %extend teca_array_collection
 {
@@ -161,7 +160,6 @@
 %ignore teca_mesh::get_y_face_arrays() const;
 %ignore teca_mesh::get_z_face_arrays() const;
 %ignore teca_mesh::get_information_arrays() const;
-%include "teca_mesh_fwd.h"
 %include "teca_mesh.h"
 TECA_PY_DYNAMIC_CAST(teca_mesh, teca_dataset)
 TECA_PY_CONST_CAST(teca_mesh)
@@ -723,7 +721,6 @@ TECA_PY_CONST_CAST(teca_table)
 %shared_ptr(teca_table_collection)
 %ignore teca_table_collection::operator=;
 %ignore teca_table_collection::operator[];
-%include "teca_table_collection_fwd.h"
 %include "teca_table_collection.h"
 %extend teca_table_collection
 {
@@ -759,7 +756,6 @@ TECA_PY_CONST_CAST(teca_table)
 %shared_ptr(teca_database)
 %ignore teca_database::operator=;
 %ignore teca_database::get_table_name(unsigned int);
-%include "teca_database_fwd.h"
 %include "teca_database.h"
 TECA_PY_DYNAMIC_CAST(teca_database, teca_dataset)
 TECA_PY_CONST_CAST(teca_database)
diff --git a/python/teca_py_iterator.h b/python/teca_py_iterator.h
index 3a54a6979..e102f4617 100644
--- a/python/teca_py_iterator.h
+++ b/python/teca_py_iterator.h
@@ -9,12 +9,12 @@
 #include "teca_py_string.h"
 #include <Python.h>
 
-/// @cond
-// this macro is used to build up dispatchers
-// PYT - type tag idnetifying the PyObject
-// ITER - PySequence* instance
-// CODE - code to execute on match
-// ST - typedef coresponding to matching tag
+/** this macro is used to build up dispatchers
+ * PYT - type tag idnetifying the PyObject
+ * ITER - PySequence* instance
+ * CODE - code to execute on match
+ * ST - typedef coresponding to matching tag
+ */
 #define TECA_PY_ITERATOR_DISPATCH_CASE(PYT, ITER, CODE) \
     if (teca_py_iterator::is_type<PYT>(ITER))           \
     {                                                   \
@@ -22,7 +22,7 @@
         CODE                                            \
     }
 
-// the macro dispatches for all the Python types
+/// the macro dispatches for all the Python types
 #define TECA_PY_ITERATOR_DISPATCH(ITER, CODE)               \
     TECA_PY_ITERATOR_DISPATCH_CASE(bool, ITER, CODE)        \
     else TECA_PY_ITERATOR_DISPATCH_CASE(int, ITER, CODE)    \
@@ -30,16 +30,15 @@
     else TECA_PY_ITERATOR_DISPATCH_CASE(char*, ITER, CODE)  \
     else TECA_PY_ITERATOR_DISPATCH_CASE(long, ITER, CODE)
 
-// this one just the numeric types
+/// this one just the numeric types
 #define TECA_PY_ITERATOR_DISPATCH_NUM(ITER, CODE)           \
     TECA_PY_ITERATOR_DISPATCH_CASE(int, ITER, CODE)         \
     else TECA_PY_ITERATOR_DISPATCH_CASE(float, ITER, CODE)  \
     else TECA_PY_ITERATOR_DISPATCH_CASE(long, ITER, CODE)
 
-// this one just strings
+/// this one just strings
 #define TECA_PY_ITERATOR_DISPATCH_STR(ITER, CODE)   \
     TECA_PY_ITERATOR_DISPATCH_CASE(char*, ITER, CODE)
-/// @endcode
 
 /// Codes for interfacing to Python iterators
 namespace teca_py_iterator
diff --git a/python/teca_py_object.h b/python/teca_py_object.h
index a29860bcd..39ddf1d68 100644
--- a/python/teca_py_object.h
+++ b/python/teca_py_object.h
@@ -12,27 +12,28 @@
 /// Codes dealing with Python objects
 namespace teca_py_object
 {
-/// @cond
+
 /// teca_py_object::cpp_tt, A traits class for working with PyObject's
 /**
-if know the Python type tag then this class gives you:
-
-::type -- C++ type that can hold the value of the PyObject.
-::is_type -- returns true if the given PyObject has this type
-::value -- convert given PyObject to its C++ type
-
-Python type tags and their coresponding PyObject's are:
-int --> PyInt/PyLong, long --> PyInt/PyLong, bool --> PyBool,
-float --> PyFloat, char* --> PyUnicode/PyString
+ * if know the Python type tag then this class gives you:
+ *
+ *     type -- C++ type that can hold the value of the PyObject.
+ *     is_type -- returns true if the given PyObject has this type
+ *     value -- convert given PyObject to its C++ type
+ *
+ * Python type tags and their coresponding PyObject's are:
+ *
+ * int --> PyInt/PyLong, long --> PyInt/PyLong, bool --> PyBool,
+ * float --> PyFloat, char* --> PyUnicode/PyString
 */
 template <typename py_t> struct cpp_tt
 {};
 
-/*
-PY_T -- C-name of python type
-CPP_T -- underlying type needed to store it on the C++ side
-PY_CHECK -- function that verifies the PyObject is this type
-PY_AS_CPP -- function that converts to the C++ type */
+/** PY_T -- C-name of python type
+ * CPP_T -- underlying type needed to store it on the C++ side
+ * PY_CHECK -- function that verifies the PyObject is this type
+ * PY_AS_CPP -- function that converts to the C++ type
+ */
 #define teca_py_object_cpp_tt_declare(PY_T, CPP_T, PY_CHECK, PY_AS_CPP) \
 template <> struct cpp_tt<PY_T>                                         \
 {                                                                       \
@@ -45,6 +46,7 @@ teca_py_object_cpp_tt_declare(long, long, PyLongCheck, PyLongToCLong)
 teca_py_object_cpp_tt_declare(float, double, PyFloat_Check, PyFloat_AsDouble)
 teca_py_object_cpp_tt_declare(char*, std::string, PyStringCheck, PyStringToCString)
 teca_py_object_cpp_tt_declare(bool, int, PyBool_Check, PyIntegerToCInt)
+
 // teca_metadata
 template <> struct cpp_tt<teca_metadata>
 {
@@ -72,28 +74,29 @@ template <> struct cpp_tt<teca_metadata>
 
 /// py_tt, traits class for working with PyObject's
 /**
-if you know the C++ type then this class gives you:
-
-::tag -- Use this in teca_py_object::cpp_t to find
-         the PyObject indentification and conversion
-         methods. see example below.
-
-::new_object -- copy construct a new PyObject
-
-here is an example of looking up the PyObject conversion
-function(value) from a known C++ type (float).
-
-float val = cpp_tt<py_tt<float>::tag>::value(obj);
-
-py_tt is used to take a C++ type and lookup the Python type
-tag. Then the type tag is used to lookup the function.
+ * if you know the C++ type then this class gives you:
+ *
+ *     tag -- Use this in teca_py_object::cpp_t to find
+ *              the PyObject indentification and conversion
+ *              methods. see example below.
+ *
+ *     new_object -- copy construct a new PyObject
+ *
+ * here is an example of looking up the PyObject conversion
+ * function(value) from a known C++ type (float).
+ *
+ *     float val = cpp_tt<py_tt<float>::tag>::value(obj);
+ *
+ * py_tt is used to take a C++ type and lookup the Python type
+ * tag. Then the type tag is used to lookup the function.
 */
 template <typename type> struct py_tt
 {};
 
 /**
-CPP_T -- underlying type needed to store it on the C++ side
-CPP_AS_PY -- function that converts from the C++ type */
+ * CPP_T -- underlying type needed to store it on the C++ side
+ * CPP_AS_PY -- function that converts from the C++ type
+ */
 #define teca_py_object_py_tt_declare(CPP_T, PY_T, CPP_AS_PY)\
 template <> struct py_tt<CPP_T>                             \
 {                                                           \
@@ -113,14 +116,14 @@ teca_py_object_py_tt_declare(unsigned long, int, CIntUToPyInteger)
 teca_py_object_py_tt_declare(unsigned long long, int, CIntULLToPyInteger)
 teca_py_object_py_tt_declare(float, float, PyFloat_FromDouble)
 teca_py_object_py_tt_declare(double, float, PyFloat_FromDouble)
-// string
+/// string
 template <> struct py_tt<std::string>
 {
     typedef char* tag;
     static PyObject *new_object(const std::string &s)
     { return CStringToPyString(s.c_str()); }
 };
-// teca_metadata
+/// teca_metadata
 template <> struct py_tt<teca_metadata>
 {
     typedef teca_metadata tag;
@@ -133,11 +136,12 @@ template <> struct py_tt<teca_metadata>
 };
 
 
-// dispatch macro.
-// OBJ -- PyObject* instance
-// CODE -- code block to execute on match
-// OT -- a typedef to the match type available in
-//       the code block
+/** dispatch macro.
+ * OBJ -- PyObject* instance
+ * CODE -- code block to execute on match
+ * OT -- a typedef to the match type available in
+ *       the code block
+ */
 #define TECA_PY_OBJECT_DISPATCH_CASE(CPP_T, PY_OBJ, CODE)   \
     if (teca_py_object::cpp_tt<CPP_T>::is_type(PY_OBJ))     \
     {                                                       \
@@ -145,7 +149,7 @@ template <> struct py_tt<teca_metadata>
         CODE                                                \
     }
 
-// all
+/// all
 #define TECA_PY_OBJECT_DISPATCH(PY_OBJ, CODE)                       \
     TECA_PY_OBJECT_DISPATCH_CASE(int, PY_OBJ, CODE)                 \
     else TECA_PY_OBJECT_DISPATCH_CASE(float, PY_OBJ, CODE)          \
@@ -153,20 +157,20 @@ template <> struct py_tt<teca_metadata>
     else TECA_PY_OBJECT_DISPATCH_CASE(long, PY_OBJ, CODE)           \
     else TECA_PY_OBJECT_DISPATCH_CASE(teca_metadata, PY_OBJ, CODE)
 
-// just numeric/POD
+/// just numeric/POD
 #define TECA_PY_OBJECT_DISPATCH_NUM(PY_OBJ, CODE)           \
     TECA_PY_OBJECT_DISPATCH_CASE(int, PY_OBJ, CODE)         \
     else TECA_PY_OBJECT_DISPATCH_CASE(float, PY_OBJ, CODE)  \
     else TECA_PY_OBJECT_DISPATCH_CASE(long, PY_OBJ, CODE)
 
-// just special cases
+/// just special cases
 #define TECA_PY_OBJECT_DISPATCH_STR(PY_OBJ, CODE)       \
     TECA_PY_OBJECT_DISPATCH_CASE(char*, PY_OBJ, CODE)
 
 #define TECA_PY_OBJECT_DISPATCH_MD(PY_OBJ, CODE)                \
     TECA_PY_OBJECT_DISPATCH_CASE(teca_metadata, PY_OBJ, CODE)
 
-/// @cond
+
 
 /// Creates a new variant array initializede with a copy of the object.
 p_teca_variant_array new_variant_array(PyObject *obj)
diff --git a/test/test_array/array.h b/test/test_array/array.h
index de54e5041..fd5b98ce7 100644
--- a/test/test_array/array.h
+++ b/test/test_array/array.h
@@ -1,12 +1,15 @@
 #ifndef array_h
 #define array_h
 
-#include "array_fwd.h"
+#include "array.h"
 #include "teca_dataset.h"
+#include "teca_shared_object.h"
 
 #include <string>
 #include <vector>
 
+TECA_SHARED_OBJECT_FORWARD_DECL(array)
+
 class teca_binary_stream;
 
 // trivial implementation of an array based datatset
diff --git a/test/test_array/array_fwd.h b/test/test_array/array_fwd.h
deleted file mode 100644
index dd90aa51b..000000000
--- a/test/test_array/array_fwd.h
+++ /dev/null
@@ -1,8 +0,0 @@
-#ifndef array_fwd_h
-#define array_fwd_h
-
-#include "teca_shared_object.h"
-
-TECA_SHARED_OBJECT_FORWARD_DECL(array)
-
-#endif
diff --git a/test/test_array/array_temporal_stats.h b/test/test_array/array_temporal_stats.h
index b887eb2e5..4029dfd60 100644
--- a/test/test_array/array_temporal_stats.h
+++ b/test/test_array/array_temporal_stats.h
@@ -2,7 +2,7 @@
 #define array_temporal_stats_h
 
 #include "teca_shared_object.h"
-#include "array_fwd.h"
+#include "array.h"
 
 #include "teca_index_reduce.h"
 #include "teca_metadata.h"