diff --git a/dev-docs/Doxyfile.in b/dev-docs/Doxyfile.in index ac818c8cf..eb09c034c 100755 --- a/dev-docs/Doxyfile.in +++ b/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 diff --git a/src/h3lib/lib/directedEdge.c b/src/h3lib/lib/directedEdge.c index 79e8cb061..f77436bb9 100644 --- a/src/h3lib/lib/directedEdge.c +++ b/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); diff --git a/src/h3lib/lib/h3Index.c b/src/h3lib/lib/h3Index.c index 3a95c7c0a..5e85d7182 100644 --- a/src/h3lib/lib/h3Index.c +++ b/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 diff --git a/src/h3lib/lib/latLng.c b/src/h3lib/lib/latLng.c index 801dc9af8..f90d9ee2b 100644 --- a/src/h3lib/lib/latLng.c +++ b/src/h3lib/lib/latLng.c @@ -179,6 +179,11 @@ 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; @@ -186,6 +191,11 @@ double H3_EXPORT(greatCircleDistanceKm)(const LatLng *a, const LatLng *b) { /** * 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); diff --git a/src/h3lib/lib/localij.c b/src/h3lib/lib/localij.c index e9444ab09..0f96adfa1 100644 --- a/src/h3lib/lib/localij.c +++ b/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; } diff --git a/src/h3lib/lib/polyfill.c b/src/h3lib/lib/polyfill.c index 4577156f1..40e67ecdc 100644 --- a/src/h3lib/lib/polyfill.c +++ b/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. */ diff --git a/src/h3lib/lib/vertex.c b/src/h3lib/lib/vertex.c index eab294071..9038389e0 100644 --- a/src/h3lib/lib/vertex.c +++ b/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);