Docstring updates (#921)

* stub for new res1 test

* better name

* formatting is happening?

* clean up test for all res 1

* failing test

* Demonstrate pass at `numUncompacted = 40`

* retry: Demonstrate pass at `numUncompacted = 40`

* should fix the formatting issue

* const array sizes to fix windows errors

* bah

* Demonstrate failure at numUncompacted = 41

* Demonstrate failure at numUncompacted = numRes1 = 842;

* Demonstrate pass at numUncompacted = 40

* back to the full failing test demonstrating the problem

* proposed fix for compact

* test other case

* comprehensive test

* NEVER for parent error

* convert compactCells to use int64_t

* docs changes

* fix typo

---------

Co-authored-by: AJ Friend <[email protected]>

Author: isaacbrodsky

dev-docs/Doxyfile.in

@@ -401,7 +401,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = ../src
+INPUT                  = ../src/h3lib "@PROJECT_BINARY_DIR@/src/h3lib/include/h3api.h"
 
 # If the value of the INPUT tag contains directories, you can use the
 # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
@@ -495,12 +495,12 @@ FILTER_SOURCE_FILES    = NO
 # Note: To get rid of all source code in the generated output, make sure also
 # VERBATIM_HEADERS is set to NO.
 
-SOURCE_BROWSER         = NO
+SOURCE_BROWSER         = YES
 
 # Setting the INLINE_SOURCES tag to YES will include the body
 # of functions and classes directly in the documentation.
 
-INLINE_SOURCES         = NO
+INLINE_SOURCES         = YES
 
 # Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct
 # doxygen to hide any special comment blocks from generated source code
@@ -648,7 +648,7 @@ ENUM_VALUES_PER_LINE   = 4
 # Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are
 # probably better off using the HTML help feature.
 
-GENERATE_TREEVIEW      = NO
+GENERATE_TREEVIEW      = YES
 
 # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be
 # used to set the initial width (in pixels) of the frame in which the tree

src/h3lib/lib/directedEdge.c

@@ -127,7 +127,7 @@ H3Error H3_EXPORT(areNeighborCells)(H3Index origin, H3Index destination,
  * destination
  * @param origin The origin H3 hexagon index
  * @param destination The destination H3 hexagon index
- * @return The directed edge H3Index, or H3_NULL on failure.
+ * @param out Output: The directed edge H3Index.
  */
 H3Error H3_EXPORT(cellsToDirectedEdge)(H3Index origin, H3Index destination,
                                        H3Index *out) {
@@ -151,7 +151,7 @@ H3Error H3_EXPORT(cellsToDirectedEdge)(H3Index origin, H3Index destination,
 /**
  * Returns the origin hexagon from the directed edge H3Index
  * @param edge The edge H3 index
- * @return The origin H3 hexagon index, or H3_NULL on failure
+ * @param out Output: The origin H3 hexagon index
  */
 H3Error H3_EXPORT(getDirectedEdgeOrigin)(H3Index edge, H3Index *out) {
     if (H3_GET_MODE(edge) != H3_DIRECTEDEDGE_MODE) {
@@ -167,7 +167,7 @@ H3Error H3_EXPORT(getDirectedEdgeOrigin)(H3Index edge, H3Index *out) {
 /**
  * Returns the destination hexagon from the directed edge H3Index
  * @param edge The edge H3 index
- * @return The destination H3 hexagon index, or H3_NULL on failure
+ * @param out Output: The destination H3 hexagon index
  */
 H3Error H3_EXPORT(getDirectedEdgeDestination)(H3Index edge, H3Index *out) {
     Direction direction = H3_GET_RESERVED_BITS(edge);

src/h3lib/lib/h3Index.c

@@ -89,8 +89,7 @@ int H3_EXPORT(getBaseCellNumber)(H3Index h) { return H3_GET_BASE_CELL(h); }
 /**
  * Converts a string representation of an H3 index into an H3 index.
  * @param str The string representation of an H3 index.
- * @return The H3 index corresponding to the string argument, or H3_NULL if
- * invalid.
+ * @param out Output: The H3 index corresponding to the string argument
  */
 H3Error H3_EXPORT(stringToH3)(const char *str, H3Index *out) {
     H3Index h = H3_NULL;
@@ -187,8 +186,7 @@ void setH3Index(H3Index *hp, int res, int baseCell, Direction initDigit) {
  *
  * @param h H3Index to find parent of
  * @param parentRes The resolution to switch to (parent, grandparent, etc)
- *
- * @return H3Index of the parent, or H3_NULL if you actually asked for a child
+ * @param out Output: H3Index of the parent
  */
 H3Error H3_EXPORT(cellToParent)(H3Index h, int parentRes, H3Index *out) {
     int childRes = H3_GET_RESOLUTION(h);
@@ -231,9 +229,8 @@ static bool _hasChildAtRes(H3Index h, int childRes) {
  *
  * @param h         H3Index to find the number of children of
  * @param childRes  The child resolution you're interested in
- *
- * @return int      Exact number of children (handles hexagons and pentagons
- *                  correctly)
+ * @param out      Output: exact number of children (handles hexagons and
+ * pentagons correctly)
  */
 H3Error H3_EXPORT(cellToChildrenSize)(H3Index h, int childRes, int64_t *out) {
     if (!_hasChildAtRes(h, childRes)) return E_RES_DOMAIN;
@@ -547,8 +544,8 @@ H3Error H3_EXPORT(compactCells)(const H3Index *h3Set, H3Index *compactedSet,
  *
  * Skips elements that are H3_NULL (i.e., 0).
  *
- * @param   compactSet  Set of compacted cells
- * @param   numCompact  The number of cells in the input compacted set
+ * @param   compactedSet  Set of compacted cells
+ * @param   numCompacted  The number of cells in the input compacted set
  * @param   outSet      Output array for decompressed cells (preallocated)
  * @param   numOut      The size of the output array to bound check against
  * @param   res         The H3 resolution to decompress to
@@ -577,7 +574,7 @@ H3Error H3_EXPORT(uncompactCells)(const H3Index *compactedSet,
  * the exact size of the uncompacted set of hexagons.
  *
  * @param   compactedSet  Set of hexagons
- * @param   numHexes      The number of hexes in the input set
+ * @param   numCompacted  The number of hexes in the input set
  * @param   res           The hexagon resolution to decompress to
  * @param   out           The number of hexagons to allocate memory for
  * @returns E_SUCCESS on success, or another value on error
@@ -1114,6 +1111,10 @@ static H3Error validateChildPos(int64_t childPos, H3Index parent,
 /**
  * Returns the position of the cell within an ordered list of all children of
  * the cell's parent at the specified resolution
+ * @param child Child cell index
+ * @param parentRes Resolution of the parent cell to find the position within
+ * @param out Output: The position of the child cell within its parents cell
+ * list of children
  */
 H3Error H3_EXPORT(cellToChildPos)(H3Index child, int parentRes, int64_t *out) {
     int childRes = H3_GET_RESOLUTION(child);
@@ -1189,7 +1190,12 @@ H3Error H3_EXPORT(cellToChildPos)(H3Index child, int parentRes, int64_t *out) {
 
 /**
  * Returns the child cell at a given position within an ordered list of all
- * children at the specified resolution */
+ * children at the specified resolution
+ * @param childPos Position within the ordered list
+ * @param parent Parent cell of the cell index to find
+ * @param childRes Resolution of the child cell index
+ * @param child Output: child cell index
+ */
 H3Error H3_EXPORT(childPosToCell)(int64_t childPos, H3Index parent,
                                   int childRes, H3Index *child) {
     // Validate resolution

src/h3lib/lib/latLng.c

@@ -179,13 +179,23 @@ double H3_EXPORT(greatCircleDistanceRads)(const LatLng *a, const LatLng *b) {
 
 /**
  * The great circle distance in kilometers between two spherical coordinates.
+ *
+ * @param  a  the first lat/lng pair (in radians)
+ * @param  b  the second lat/lng pair (in radians)
+ *
+ * @return    the great circle distance in kilometers between a and b
  */
 double H3_EXPORT(greatCircleDistanceKm)(const LatLng *a, const LatLng *b) {
     return H3_EXPORT(greatCircleDistanceRads)(a, b) * EARTH_RADIUS_KM;
 }
 
 /**
  * The great circle distance in meters between two spherical coordinates.
+ *
+ * @param  a  the first lat/lng pair (in radians)
+ * @param  b  the second lat/lng pair (in radians)
+ *
+ * @return    the great circle distance in meters between a and b
  */
 double H3_EXPORT(greatCircleDistanceM)(const LatLng *a, const LatLng *b) {
     return H3_EXPORT(greatCircleDistanceKm)(a, b) * 1000;
@@ -419,6 +429,10 @@ H3Error H3_EXPORT(cellAreaRads2)(H3Index cell, double *out) {
 
 /**
  * Area of H3 cell in kilometers^2.
+ *
+ * @param   cell  H3 cell
+ * @param    out  cell area in kilometers^2
+ * @return        E_SUCCESS on success, or an error code otherwise
  */
 H3Error H3_EXPORT(cellAreaKm2)(H3Index cell, double *out) {
     H3Error err = H3_EXPORT(cellAreaRads2)(cell, out);
@@ -430,6 +444,10 @@ H3Error H3_EXPORT(cellAreaKm2)(H3Index cell, double *out) {
 
 /**
  * Area of H3 cell in meters^2.
+ *
+ * @param   cell  H3 cell
+ * @param    out  cell area in meters^2
+ * @return        E_SUCCESS on success, or an error code otherwise
  */
 H3Error H3_EXPORT(cellAreaM2)(H3Index cell, double *out) {
     H3Error err = H3_EXPORT(cellAreaKm2)(cell, out);
@@ -443,8 +461,8 @@ H3Error H3_EXPORT(cellAreaM2)(H3Index cell, double *out) {
  * Length of a directed edge in radians.
  *
  * @param   edge  H3 directed edge
- *
- * @return        length in radians
+ * @param    length  length in radians
+ * @return        E_SUCCESS on success, or an error code otherwise
  */
 H3Error H3_EXPORT(edgeLengthRads)(H3Index edge, double *length) {
     CellBoundary cb;
@@ -465,6 +483,10 @@ H3Error H3_EXPORT(edgeLengthRads)(H3Index edge, double *length) {
 
 /**
  * Length of a directed edge in kilometers.
+ *
+ * @param   edge  H3 directed edge
+ * @param    length  length in kilometers
+ * @return        E_SUCCESS on success, or an error code otherwise
  */
 H3Error H3_EXPORT(edgeLengthKm)(H3Index edge, double *length) {
     H3Error err = H3_EXPORT(edgeLengthRads)(edge, length);
@@ -474,6 +496,10 @@ H3Error H3_EXPORT(edgeLengthKm)(H3Index edge, double *length) {
 
 /**
  * Length of a directed edge in meters.
+ *
+ * @param   edge  H3 directed edge
+ * @param    length  length in meters
+ * @return        E_SUCCESS on success, or an error code otherwise
  */
 H3Error H3_EXPORT(edgeLengthM)(H3Index edge, double *length) {
     H3Error err = H3_EXPORT(edgeLengthKm)(edge, length);

src/h3lib/lib/localij.c

@@ -525,13 +525,13 @@ H3Error localIjkToCell(H3Index origin, const CoordIJK *ijk, H3Index *out) {
  * @param out ij coordinates of the index will be placed here on success
  * @return 0 on success, or another value on failure.
  */
-H3Error H3_EXPORT(cellToLocalIj)(H3Index origin, H3Index h3, uint32_t mode,
+H3Error H3_EXPORT(cellToLocalIj)(H3Index origin, H3Index index, uint32_t mode,
                                  CoordIJ *out) {
     if (mode != 0) {
         return E_OPTION_INVALID;
     }
     CoordIJK ijk;
-    H3Error failed = cellToLocalIjk(origin, h3, &ijk);
+    H3Error failed = cellToLocalIjk(origin, index, &ijk);
     if (failed) {
         return failed;
     }
@@ -554,9 +554,9 @@ H3Error H3_EXPORT(cellToLocalIj)(H3Index origin, H3Index h3, uint32_t mode,
  * to be compatible across different versions of H3.
  *
  * @param origin An anchoring index for the ij coordinate system.
- * @param out ij coordinates to index.
+ * @param ij ij coordinates to index.
  * @param mode Mode, must be 0
- * @param index Index will be placed here on success.
+ * @param out Index will be placed here on success.
  * @return 0 on success, or another value on failure.
  */
 H3Error H3_EXPORT(localIjToCell)(H3Index origin, const CoordIJ *ij,
@@ -582,16 +582,17 @@ H3Error H3_EXPORT(localIjToCell)(H3Index origin, const CoordIJ *ij,
  *
  * @param origin Index to find the distance from.
  * @param index Index to find the distance to.
- * @return The distance, or a negative number if the library could not
- * compute the distance.
+ * @param out The distance in cells
+ * @returns E_SUCCESS on success, or another value if the library cannot compute
+ * the distance.
  */
-H3Error H3_EXPORT(gridDistance)(H3Index origin, H3Index h3, int64_t *out) {
+H3Error H3_EXPORT(gridDistance)(H3Index origin, H3Index index, int64_t *out) {
     CoordIJK originIjk, h3Ijk;
     H3Error originError = cellToLocalIjk(origin, origin, &originIjk);
     if (originError) {
         return originError;
     }
-    H3Error destError = cellToLocalIjk(origin, h3, &h3Ijk);
+    H3Error destError = cellToLocalIjk(origin, index, &h3Ijk);
     if (destError) {
         return destError;
     }

src/h3lib/lib/polyfill.c

@@ -723,8 +723,9 @@ static double getAverageCellArea(int res) {
 /**
  * maxPolygonToCellsSize returns the number of cells to allocate space for
  * when performing a polygonToCells on the given GeoJSON-like data structure.
- * @param geoPolygon A GeoJSON-like data structure indicating the poly to fill
+ * @param polygon A GeoJSON-like data structure indicating the poly to fill
  * @param res Hexagon resolution (0-15)
+ * @param flags Bit mask of option flags
  * @param out number of cells to allocate for
  * @return 0 (E_SUCCESS) on success.
  */

src/h3lib/lib/vertex.c

@@ -205,6 +205,7 @@ static const int revNeighborDirectionsHex[NUM_DIGITS] = {
  * H3_NULL if the vertex is invalid
  * @param cell    Cell to get the vertex for
  * @param vertexNum Number (index) of the vertex to calculate
+ * @param out Output: The vertex index
  */
 H3Error H3_EXPORT(cellToVertex)(H3Index cell, int vertexNum, H3Index *out) {
     int cellIsPentagon = H3_EXPORT(isPentagon)(cell);