DOxygen Documentation

[r-barnes]

I have an example of DOxygen-style documentation from my own work here: https://github.com/r-barnes/richdem/blob/master/include/richdem/depressions/Barnes2014.hpp

Excerpted:

/**
  @brief  Fills all pits and removes all digital dams from a DEM [one-line brief description]

    [paragraph-style longer description]
    Priority-Flood starts on the edges of the DEM and then works its way
    inwards using a priority queue to determine the lowest cell which has
    a path to the edge. The neighbours of this cell are added to the priority
    queue. If the neighbours are lower than the cell which is adding them, then
    they are raised to match its elevation; this fills depressions.

  @param[in,out]  elevations   A grid of cell elevations [list of input arguments

  @return True if XXX; otherwise, False [what the return value is/means]

  @pre
    1. @p elevations contains the elevations of every cell or a value _NoData_
       for cells not part of the DEM. Note that the _NoData_ value is assumed to
       be a negative number less than any actual data value. [pre-conditions]

  @post
    1. @p elevations contains the elevations of every cell or a value _NoData_
       for cells not part of the DEM.
    2. @p elevations contains no landscape depressions or digital dams. [postconditions]

  @correctness
    The correctness of this command is determined by inspection. (TODO)
    [The correctness field is one I've added to the RichDEM generator to make it more explicit how correctness is shown
*/
template <Topology topo, class elev_t>
bool PriorityFlood_Original(Array2D<elev_t> &elevations){

[r-barnes]

You can also use inline documentation for things like classes, like so:

template<class T>
class Array2D {
 public:
  std::string filename;             ///< File, if any, from which the data was loaded
  std::string basename;             ///< Filename without path or extension
  std::vector<double> geotransform; ///< Geotransform of the raster
  std::string projection;           ///< Projection of the raster
  std::map<std::string, std::string> metadata; ///< Raster's metadata in key-value pairs

[r-barnes]

But if you can get the documentation mostly there, I can make sure the syntax is okay.

[r-barnes]

I'll hold off on the Python documentation for now, since that can mostly be copied from the C++ code.