docs(observers): more docstrings and rst for write_to_dataset_observer

docs/source/cxx/observers/write_to_dataset_observer.rst

@@ -1,14 +1,21 @@
-XXX Observer
-============
+Template for Observer to Write To Dataset
+=========================================
 
-// TODO(CB) write doc
+Header file: ``<libs/observers/write_to_dataset_observer.hpp>``
+`[source] <https://github.com/yoctoyotta1024/CLEO/blob/main/libs/observers/write_to_dataset_observer.hpp>`_
 
-Header file: ``<libs/observers/XXX_observer.hpp>``
-`[source] <https://github.com/yoctoyotta1024/CLEO/blob/main/libs/observers/XXX_observer.hpp>`_
-
-.. doxygenstruct:: XXXObserver
+.. doxygenclass:: DoWriteToDataset
    :project: observers
    :private-members:
    :protected-members:
    :members:
    :undoc-members:
+
+.. doxygenfunction:: WriteToDatasetObserver(const unsigned int interval, ParallelWriteData parallel_write)
+   :project: observers
+
+.. doxygenfunction:: WriteToDatasetObserver(const unsigned int interval, const Dataset<Store> &dataset, CollectData collect_data)
+   :project: observers
+
+.. doxygenfunction:: WriteToDatasetObserver(const unsigned int interval, const Dataset<Store> &dataset, CollectData collect_data, RaggedCount ragged_count)
+   :project: observers

docs/source/cxx/zarr/xarray_zarr_array.rst

@@ -13,7 +13,10 @@ Header file: ``<libs/zarr/xarray_zarr_array.hpp>``
 .. doxygenfunction:: vecstr_to_string
    :project: zarr
 
-.. doxygenfunction:: make_xarray_metadata
+.. doxygenfunction:: make_xarray_metadata(const std::string_view units, const std::string_view dtype, const double scale_factor, const std::vector<std::string>& dimnames)
+   :project: zarr
+
+.. doxygenfunction:: make_xarray_metadata(const std::string_view units, const std::string_view dtype, const double scale_factor, const std::vector<std::string>& dimnames, const std::string_view sampledimname)
    :project: zarr
 
 .. doxygenclass:: XarrayZarrArray

libs/observers/write_to_dataset_observer.hpp

@@ -9,7 +9,7 @@
  * Author: Clara Bayley (CB)
  * Additional Contributors:
  * -----
- * Last Modified: Tuesday 9th April 2024
+ * Last Modified: Thursday 11th April 2024
  * Modified By: CB
  * -----
  * License: BSD 3-Clause "New" or "Revised" License
@@ -33,41 +33,74 @@
 #include "./parallel_write_data.hpp"
 #include "zarr/dataset.hpp"
 
-/* template class for to call a function during the at_start_step function of an observer
-in order to collect variables from gridboxes and/or superdroplets in parallel and then write them
-to arrays in a dataset at a constant time interval. */
+/**
+ * @class DoWriteToDataset
+ * @brief Templated class for writing data from gridboxes and/or superdroplets to a dataset at the
+ * constant time intervals by calling the operator of the ParallelWriteData type at the start of
+ * each step.
+ * @tparam ParallelWriteData Type of function-like object to call during at_start_step.
+ */
 template <typename ParallelWriteData>
 class DoWriteToDataset {
  private:
-  ParallelWriteData parallel_write;  ///< function like object to call during at_start_step
+  ParallelWriteData parallel_write; /**< Function-like object to call during at_start_step. */
 
- public:
+  /**
+   * @brief Constructor for DoWriteToDataset.
+   * @param parallel_write Function-like object to call during at_start_step.
+   */
   explicit DoWriteToDataset(ParallelWriteData parallel_write) : parallel_write(parallel_write) {}
 
+  /**
+   * @brief Placeholder for before timestepping functionality and to make class satisfy observer
+   * concept.
+   */
   void before_timestepping(const viewd_constgbx d_gbxs) const {
     std::cout << "observer includes write in dataset observer\n";
   }
 
+  /**
+   * @brief Placeholder for after timestepping functionality and to make class satisfy observer
+   * concept.
+   */
   void after_timestepping() const {}
 
+  /**
+   * @brief Calls the parallel_write function during at_start_step.
+   * @param t_mdl Current model time.
+   * @param d_gbxs View of gridboxes.
+   * @param totsupers View of superdroplets.
+   */
   void at_start_step(const unsigned int t_mdl, const viewd_constgbx d_gbxs,
                      const viewd_constsupers totsupers) const {
     parallel_write(d_gbxs, totsupers);
   }
 };
 
-/* constructs observer which writes some data in parallel according to parallel_write at the start
-of a constant timestep 'interval' using instances of the ConstTstepObserver and DoWriteToDataset
-classes */
+/**
+ * @brief Constructs an observer to write data from gridboxes and/or superdroplets to a dataset at a
+ * constant time interval according to the ParallelWriteData struct.
+ * @tparam ParallelWriteData Type of function-like object to call during at_start_step.
+ * @param interval Constant timestep interval.
+ * @param parallel_write Function-like object to call during at_start_step.
+ * @return Constructed observer.
+ */
 template <typename ParallelWriteData>
 inline Observer auto WriteToDatasetObserver(const unsigned int interval,
                                             ParallelWriteData parallel_write) {
   return ConstTstepObserver(interval, DoWriteToDataset(parallel_write));
 }
 
-/* constructs observer which writes some data from gridboxes in parallel into arrays in a dataset
-according to parallel_write at the start of a constant timestep 'interval' using instances of the
-ConstTstepObserver and DoWriteToDataset classes */
+/**
+ * @brief Constructs an observer to write data from gridboxes to arrays in a dataset at a
+ * constant time interval using a range policy parallelism over the gridboxes.
+ * @tparam Store Type of store for dataset.
+ * @tparam CollectData Type of collect data function.
+ * @param interval Constant timestep interval.
+ * @param dataset Dataset to write data to.
+ * @param collect_data Function to collect data from gridboxes.
+ * @return Constructed observer.
+ */
 template <typename Store, CollectDataForDataset<Store> CollectData>
 inline Observer auto WriteToDatasetObserver(const unsigned int interval,
                                             const Dataset<Store> &dataset,
@@ -77,9 +110,18 @@ inline Observer auto WriteToDatasetObserver(const unsigned int interval,
   return ConstTstepObserver(interval, DoWriteToDataset(parallel_write));
 }
 
-/* constructs observer which writes some data from superdroplets in parallel into ragged arrays in a
-dataset according to parallel_write at the start of a constant timestep 'interval' using instances
-of the ConstTstepObserver and DoWriteToDataset classes */
+/**
+ * @brief Constructs an observer to write data from superdroplets to ragged arrays in a dataset
+ * at a constant time interval.
+ * @tparam Store Type of store for dataset.
+ * @tparam CollectData Type of collect data function.
+ * @tparam RaggedCount Type of collect ragged count function.
+ * @param interval Constant timestep interval.
+ * @param dataset Dataset to write data to.
+ * @param collect_data Function to collect data from superdroplets.
+ * @param ragged_count Function to collect ragged count for superdroplet data arrays(s).
+ * @return Constructed observer.
+ */
 template <typename Store, CollectDataForDataset<Store> CollectData,
           CollectRaggedCount<Store> RaggedCount>
 inline Observer auto WriteToDatasetObserver(const unsigned int interval,