From ade553e85275bec4df492e02e617cda0da5d814c Mon Sep 17 00:00:00 2001
From: Jonathan Lifflander <jliffla@sandia.gov>
Date: Mon, 15 Jun 2020 19:24:04 -0700
Subject: [PATCH] #672: docs: write doxygen for scatter

---
 src/vt/collective/scatter/scatter.h | 42 +++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/src/vt/collective/scatter/scatter.h b/src/vt/collective/scatter/scatter.h
index 756f8e742b..23d50338d4 100644
--- a/src/vt/collective/scatter/scatter.h
+++ b/src/vt/collective/scatter/scatter.h
@@ -56,12 +56,32 @@
 
 namespace vt { namespace collective { namespace scatter {
 
+/**
+ * \struct Scatter
+ *
+ * \brief Scatter data across all nodes from a single origin
+ *
+ * Performs an asynchronous scatter over all the nodes in the
+ * communicator/runtime. Recursively bisect the data as we move down the
+ * spanning tree.
+ */
 struct Scatter : virtual collective::tree::Tree {
   using FuncSizeType = std::function<std::size_t(NodeType)>;
   using FuncDataType = std::function<void(NodeType, void*)>;
 
+  /**
+   * \internal \brief Construct a scatter manager
+   */
   Scatter();
 
+  /**
+   * \brief Scatter data to all nodes
+   *
+   * \param[in] total_size total size of data to scatter
+   * \param[in] max_proc_size max data to be scattered to any node
+   * \param[in] size_fn callback to get size for each node
+   * \param[in] data_fn callback to get data for each node
+   */
   template <typename MessageT, ActiveTypedFnType<MessageT>* f>
   void scatter(
     std::size_t const& total_size, std::size_t const& max_proc_size,
@@ -69,13 +89,35 @@ struct Scatter : virtual collective::tree::Tree {
   );
 
 protected:
+  /**
+   * \internal \brief Receive scattered data down the spanning tree
+   *
+   * \param[in] msg the scatter message
+   */
   void scatterIn(ScatterMsg* msg);
 
 private:
+  /**
+   * \internal \brief Helper function to scatter data
+   *
+   * \param[in] node the current code
+   * \param[in] ptr pointer to raw data
+   * \param[in] elm_size bytes per element of raw data
+   * \param[in] size_fn callback to get size for each node
+   * \param[in] data_fn callback to get data for each node
+   *
+   * \return incremented point after scatter is complete
+   */
   char* applyScatterRecur(
     NodeType node, char* ptr, std::size_t elm_size, FuncSizeType size_fn,
     FuncDataType data_fn
   );
+
+  /**
+   * \internal \brief Active function to receive scattered data
+   *
+   * \param[in] msg the scatter message
+   */
   static void scatterHandler(ScatterMsg* msg);
 };