Add Doxygen Documentation for libcuspatial

cpp/doxygen/main_page.md

@@ -0,0 +1,3 @@
+# libcuspatial
+
+libcuspatial is a GPU-accelerated C++ library for spatial data analysis including distance and trajectory computations, spatial data indexing and spatial join operations.

cpp/doxygen/rapids.css

@@ -0,0 +1,119 @@
+/*
+ * Copyright (c) 2022, NVIDIA CORPORATION.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/* sm-dox is the CSS class Doxygen uses for the main navigation menu bar */
+.sm-dox {
+  background-image:none;              /* override Doxygen background images */
+  background-color: #7306ff;        /* rapids.ai menu background purple */
+}
+
+/* Menu links */
+.sm-dox a, 
+.sm-dox a:focus,
+.sm-dox a:hover,
+.sm-dox a:active,
+.sm-dox a.highlighted {
+  background-image:none;              /* override Doxygen background images */
+  color: white;                     /* rapids.ai menu white font */
+  font-family:"Open Sans",sans-serif; /* rapids.ai menu font family */
+  /* rapids.ai uppercase menus, no decoration or shadows, 1em size */
+  text-decoration: none;              
+  text-transform: uppercase;
+  text-shadow: none;
+  font-weight: normal;
+  font-size: 1em;
+}
+
+.sm-dox a:hover {
+  background-image:none;                    /* override Doxygen background images */
+  color: #a785e7;                         /* rapids.ai menu text hover color */
+  -webkit-transition: all 0.3s ease-in-out; /* rapids.ai menu fade when hover */
+  -moz-transition: all 0.3s ease-in-out;
+  -o-transition: all 0.3s ease-in-out;
+  transition: all 0.3s ease-in-out;
+}
+
+/* These are the triangles to the right of menus that open up. Make them match the font/fade */
+.sm-dox a span.sub-arrow {
+  border-top-color: white;
+}
+
+.sm-dox a:hover span.sub-arrow {
+  border-top-color: #a785e7;              /* rapids.ai menu text hover color */
+  -webkit-transition: all 0.3s ease-in-out; /* rapids.ai menu fade when hover */
+  -moz-transition: all 0.3s ease-in-out;
+  -o-transition: all 0.3s ease-in-out;
+  transition: all 0.3s ease-in-out;
+}
+
+/* sm-dox ul is the drop-down menus that appear when you mouse over hierarchical menus.
+   Make these white but highlight hovered items with rapids purple background and white text. */
+.sm-dox ul a {
+  font-size: 1em;
+}
+
+.sm-dox ul a:hover {
+  background-image:none;
+  background-color: #7306ff;            
+  font-size: 1em;
+  text-shadow: none;
+  -webkit-transition: all 0.3s ease-in-out;
+  -moz-transition: all 0.3s ease-in-out;
+  -o-transition: all 0.3s ease-in-out;
+  transition: all 0.3s ease-in-out;
+}
+
+/* Sub menu (underneath the main Doxygen bar) is a ul with class navpath that shows
+   the C++ class hierarchy.
+*/
+.navpath ul
+{
+  font-size: 13px;             /* Bigger than Doxygen default looks a bit better */
+  background-image:none;       /* Override Doxygen gradient background image */
+  background-color: #FAF6FF; /* A nearly white RAPIDS purple background */
+  border-top:none;             /* Override Doxygen top border for class hierarchy menu since 
+                                  it doesn't match the menu above. */
+}
+
+/* Note we don't override the background on li tags here because we want to keep the ">"
+   background images Doxygen uses here as separators */
+.navpath li.navelem {
+  background-color: #FAF6FF;   /* A nearly white RAPIDS purple background */
+}
+
+/* Add some CSS to make class / function lists nicer in the presence of long templated names */
+
+.directory td.entry {
+  white-space: normal;                /* Allow text wrapping for long class names */
+  min-width:   512px;                 /* But don't wrap them too much. */
+
+  /* This indent and padding causes any long class names that are wrapped to be indented on 
+     wrapped lines */
+  text-indent: -65px;
+  padding-left: 55px;
+}
+
+/* Prevent arrows from being negatively indented */
+.arrow {
+  text-indent: 0px;
+  padding-left: 10px;
+}
+
+/* Prevent icons from being negatively indented */
+.icona {
+  text-indent: 0px;
+  padding-left: 0px;
+}

cpp/include/cuspatial/constants.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020, NVIDIA CORPORATION.
+ * Copyright (c) 2020-2022, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,8 +18,17 @@
 
 #pragma once
 
+/**
+ * @addtogroup cuspatial_constants
+ * @{
+ */
+
 constexpr double DEGREE_TO_RADIAN = M_PI / 180.0;
 constexpr double RADIAN_TO_DEGREE = 180.0 / M_PI;
 
 constexpr double EARTH_RADIUS_KM                = 6371.0;
 constexpr double EARTH_CIRCUMFERENCE_EQUATOR_KM = 40000.0;
+
+/**
+ * @} // end of doxygen group
+ */

cpp/include/cuspatial/coordinate_transform.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019-2020, NVIDIA CORPORATION.
+ * Copyright (c) 2019-2022, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,6 +21,11 @@
 
 namespace cuspatial {
 
+/**
+ * @addtogroup coordinate_transform
+ * @{
+ */
+
 /**
  * @brief Translates lon/lat relative to origin and converts to cartesian (x/y) coordinates.
  *
@@ -39,4 +44,8 @@ std::pair<std::unique_ptr<cudf::column>, std::unique_ptr<cudf::column>> lonlat_t
   cudf::column_view const& input_lat,
   rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
 
+/**
+ * @} // end of doxygen group
+ */
+
 }  // namespace cuspatial

cpp/include/cuspatial/cubic_spline.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020, NVIDIA CORPORATION.
+ * Copyright (c) 2020-2022, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,6 +24,11 @@
 
 namespace cuspatial {
 
+/**
+ * @addtogroup cubic_spline
+ * @{
+ */
+
 /**
  * @brief Create a table of cubic spline coefficients from columns of coordinates.
  *
@@ -85,4 +90,7 @@ std::unique_ptr<cudf::table> cubicspline_coefficients(
   cudf::column_view const& offsets,
   rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
 
+/**
+ * @} // end of doxygen group
+ */
 }  // namespace cuspatial

cpp/include/cuspatial/distances/linestring_distance.hpp

@@ -23,6 +23,11 @@
 
 namespace cuspatial {
 
+/**
+ * @addtogroup distance
+ * @{
+ */
+
 /**
  * @brief Compute shortest distance between pairs of linestrings (a.k.a. polylines)
  *
@@ -31,7 +36,7 @@ namespace cuspatial {
  * the distance is 0.
  *
  * The following example contains 4 pairs of linestrings.
- *
+ * ```
  * First pair:
  * (0, 1) -> (1, 0) -> (-1, 0)
  * (1, 1) -> (2, 1) -> (2, 0) -> (3, 0)
@@ -78,15 +83,16 @@ namespace cuspatial {
  * linestring2_points_y: {1, 1, 0, 0, 0, 1, 2, 0, 2, 1, 5, 0}
  *
  * Result: {sqrt(2.0)/2, 1, 0, 0}
+ * ```
  *
- * @param linestring1_offsets Indices of the first point of the first linestring of each pair.
- * @param linestring1_points_x x-components of points in the first linestring of each pair.
- * @param linestring1_points_y y-component of points in the first linestring of each pair.
- * @param linestring2_offsets Indices of the first point of the second linestring of each pair.
- * @param linestring2_points_x x-component of points in the first linestring of each pair.
- * @param linestring2_points_y y-component of points in the first linestring of each pair.
- * @param mr Device memory resource used to allocate the returned column's device memory.
- * @return A column of shortest distances between each pair of linestrings.
+ * @param linestring1_offsets Indices of the first point of the first linestring of each pair
+ * @param linestring1_points_x x-components of points in the first linestring of each pair
+ * @param linestring1_points_y y-component of points in the first linestring of each pair
+ * @param linestring2_offsets Indices of the second point of the second linestring of each pair
+ * @param linestring2_points_x x-component of points in the second linestring of each pair
+ * @param linestring2_points_y y-component of points in the second linestring of each pair
+ * @param mr Device memory resource used to allocate the returned column's device memory
+ * @return A column of shortest distances between each pair of linestrings
  *
  * @note If any of the linestring contains less than 2 points, the behavior is undefined.
  *
@@ -106,4 +112,8 @@ std::unique_ptr<cudf::column> pairwise_linestring_distance(
   cudf::column_view const& linestring2_points_y,
   rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
 
+/**
+ * @} // end of doxygen group
+ */
+
 }  // namespace cuspatial

cpp/include/cuspatial/error.hpp

@@ -23,6 +23,11 @@
 
 namespace cuspatial {
 
+/**
+ * @addtogroup exception
+ * @{
+ */
+
 /**---------------------------------------------------------------------------*
  * @brief Exception thrown when logical precondition is violated.
  *
@@ -42,6 +47,10 @@ struct cuda_error : public std::runtime_error {
   cuda_error(std::string const& message) : std::runtime_error(message) {}
 };
 
+/**
+ * @} // end of doxygen group
+ */
+
 }  // namespace cuspatial
 
 #define CUSPATIAL_STRINGIFY_DETAIL(x) #x

cpp/include/cuspatial/experimental/haversine.cuh

@@ -27,6 +27,8 @@ namespace cuspatial {
 /**
  * @brief Compute haversine distances between points in set A to the corresponding points in set B.
  *
+ * @ingroup distance
+ *
  * Computes N haversine distances, where N is `std::distance(a_lonlat_first, a_lonlat_last)`.
  * The distance for each `a_lonlat[i]` and `b_lonlat[i]` point pair is assigned to
  * `distance_first[i]`. `distance_first` must be an iterator to output storage allocated for N