add inline documentation to Gather class

Author: dpgraham4401

src/core/bindings.cpp

@@ -47,6 +47,6 @@ PYBIND11_MODULE(_gather, m) {
       .def_readwrite("nx", &Gather::nx)
       .def_readwrite("dt", &Gather::dt)
       .def_readonly("data", &Gather::data)
-      .def("__str__", &Gather::display)
+      .def("__str__", &Gather::str)
       .def("from_bin_file", &Gather::from_bin_file);
 }

src/core/gather/gather.hpp

@@ -25,10 +25,32 @@ class Gather {
     data.resize(nt * nx);
   }
 
-  [[nodiscard]] std::string display() const {
+  /**
+   * @brief a helper function used for Python __str__ method.
+   */
+  [[nodiscard]] std::string str() const {
     return "Gather id: " + std::to_string(id);
   }
 
+  /**
+   * @brief overload the output stream operator for Gather.
+   */
+  friend std::ostream &operator<<(std::ostream &os, const Gather &gather) {
+    os << "Gather id: " << gather.id << std::endl;
+    return os;
+  }
+
+  /**
+   * @brief Read a binary file and create a Gather object.
+   *
+   * This function takes a file path (string), the number of time samples (nt),
+   * and the number of traces (nx) to read from the binary file.
+   *
+   * @param path the path to the binary file.
+   * @param nt the number of time samples per trace.
+   * @param nx the number of traces per gather.
+   * @return Gather object populated with data from the file.
+   */
   static Gather from_bin_file(const std::string &path, int nt, int nx,
                               double dt = 0.0) {
     std::ifstream file(path, std::ios::binary);