Update doxygen documentation

HighMap/include/highmap/hydrology.hpp

@@ -5,12 +5,23 @@
 /**
  * @file hydrology.hpp
  * @author Otto Link (otto.link.bv@gmail.com)
- * @brief
+ * @brief Header file for hydrological modeling functions and utilities.
+ *
+ * This header file declares functions and utilities for hydrological modeling,
+ * including tools for computing flow directions, flow accumulation, and
+ * identifying flow sinks within heightmaps. It supports multiple flow direction
+ * models and the D8 model for flow direction and accumulation calculations.
+ *
+ * Key functionalities include:
+ * - Computation of flow directions and flow accumulations using various models.
+ * - Identification of flow sinks in heightmaps.
+ * - Support for multiple flow direction models with customizable flow-partition
+ * exponents.
+ *
  * @version 0.1
  * @date 2023-05-06
  *
- * @copyright Copyright (c) 2023
- *
+ * @copyright Copyright (c) 2023 Otto Link
  */
 #pragma once
 
@@ -20,21 +31,32 @@ namespace hmap
 {
 
 /**
- * @brief Return the number of input drainage paths for each cell based on the
- * D8 flow direction map.
- *
- * @param d8 Flow direction according to the D8 model.
- * @return Array Number of neighbors with flow directions pointing to the
- * current cell.
+ * @brief Computes the number of drainage paths for each cell based on the D8
+ * flow direction model.
+ *
+ * This function calculates the number of neighboring cells that have flow
+ * directions pointing to the current cell according to the D8 model. The result
+ * is an array where each cell contains the count of its incoming flow
+ * directions.
+ *
+ * @param d8 Input array representing the flow directions according to the D8
+ * model. Each cell value indicates the direction of flow according to the D8
+ * convention.
+ * @return Array An array where each cell contains the number of incoming flow
+ * directions pointing to it.
  */
 Array d8_compute_ndip(const Array &d8);
 
 /**
- * @brief Find the indices `(i, j)` of flow sinks within the heightmap.
+ * @brief Identifies the indices of flow sinks within the heightmap.
  *
- * @param z Input array.
- * @param is Indices `i` of the sinks (output).
- * @param js Indices `j` of the sinks (output).
+ * This function locates the cells in the heightmap that are flow sinks (cells
+ * with no outflow) and returns their indices. Flow sinks are cells that do not
+ * direct flow to any other cell.
+ *
+ * @param z Input array representing the heightmap values.
+ * @param is Output vector containing the row indices `i` of the flow sinks.
+ * @param js Output vector containing the column indices `j` of the flow sinks.
  *
  * **Example**
  * @include ex_find_flow_sinks.cpp
@@ -44,11 +66,17 @@ void find_flow_sinks(const Array      &z,
                      std::vector<int> &js);
 
 /**
- * @brief Return flow accumulation in each cell using the D8 flow direction
- * model \cite Zhou2019.
+ * @brief Computes the flow accumulation for each cell using the D8 flow
+ * direction model.
+ *
+ * This function calculates the flow accumulation for each cell in the heightmap
+ * based on the D8 flow direction model \cite Zhou2019. Flow accumulation
+ * represents the total amount of flow that accumulates at each cell from
+ * upstream cells.
  *
- * @param z Input array.
- * @return Array Flow accumulation.
+ * @param z Input array representing the heightmap values.
+ * @return Array An array where each cell contains the computed flow
+ * accumulation.
  *
  * **Example**
  * @include ex_flow_accumulation_d8.cpp
@@ -60,17 +88,22 @@ void find_flow_sinks(const Array      &z,
  * @see flow_direction_d8
  */
 Array flow_accumulation_d8(const Array &z);
-
 /**
- * @brief Return flow accumulation in each cell using the multiple flow
- * direction model \cite Qin2007
- *
- * @param z  Input array.
- * @param talus_ref Reference talus used to localy define the flow-partition
- * exponent: small values of `talus_ref` will lead to thinner flow streams (@see
- * flow_direction_dinf). The maximum talus value of the heighmap can be used as
- * a reference.
- * @return Array
+ * @brief Computes the flow accumulation for each cell using the Multiple Flow
+ * Direction (MFD) model.
+ *
+ * This function calculates the flow accumulation for each cell based on the MFD
+ * model \cite Qin2007. Flow accumulation represents the total amount of flow
+ * that accumulates at each cell from upstream cells. The flow-partition
+ * exponent is locally defined using a reference talus value, where smaller
+ * values of `talus_ref` will lead to narrower flow streams. The maximum talus
+ * value of the heightmap can be used as a reference.
+ *
+ * @param z Input array representing the heightmap values.
+ * @param talus_ref Reference talus used to locally define the flow-partition
+ * exponent. Small values will result in thinner flow streams.
+ * @return Array An array where each cell contains the computed flow
+ * accumulation.
  *
  * **Example**
  * @include ex_flow_accumulation_dinf.cpp
@@ -84,32 +117,41 @@ Array flow_accumulation_d8(const Array &z);
 Array flow_accumulation_dinf(const Array &z, float talus_ref);
 
 /**
- * @brief Return the direction of flow from each cell to its downslope neighbor
- * using the D8 model @cite Greenlee1987.
+ * @brief Computes the flow direction from each cell to its downslope neighbor
+ * using the D8 model.
  *
- * **Flow direction nomenclature**
+ * This function calculates the direction of flow for each cell in the heightmap
+ * using the D8 flow direction model @cite Greenlee1987. The D8 model defines
+ * eight possible flow directions as follows:
  * @verbatim
-   5 6 7
-   4 . 0
-   3 2 1
- @endverbatim
+ *   5 6 7
+ *   4 . 0
+ *   3 2 1
+ * @endverbatim
  *
- * @param z Input array.
- * @return Array Flow direction (D8 nomenclature).
+ * @param z Input array representing the heightmap values.
+ * @return Array An array where each cell contains the flow direction according
+ * to the D8 nomenclature.
  *
  * @see flow_accumulation_d8
  */
 Array flow_direction_d8(const Array &z);
 
 /**
- * @brief Return flow direction in each cell and for each directions using the
- * multiple flow direction model \cite Qin2007
- *
- * @param z Input array.
- * @param talus_ref Reference talus used to localy define the flow-partition
- * exponent. Small values of `talus_ref` will lead to thinner flow streams. The
- * maximum talus value of the heighmap can be used as a reference.
- * @return std::vector<Array> Weight for each flow directions at every cells.
+ * @brief Computes the flow direction and weights for each direction using the
+ * Multiple Flow Direction (MFD) model.
+ *
+ * This function calculates the flow direction for each cell and provides the
+ * weight for each possible flow direction using the MFD model \cite Qin2007.
+ * The flow-partition exponent is determined using a reference talus value.
+ * Smaller values of `talus_ref` will lead to thinner flow streams. The maximum
+ * talus value of the heightmap can be used as a reference.
+ *
+ * @param z Input array representing the heightmap values.
+ * @param talus_ref Reference talus used to locally define the flow-partition
+ * exponent. Smaller values will result in thinner flow streams.
+ * @return std::vector<Array> A vector of arrays, each containing the weights
+ * for flow directions at every cell.
  */
 std::vector<Array> flow_direction_dinf(const Array &z, float talus_ref);