Improve C++ source and header organization

[harrism]

** Update: converting to epic/tasklist **

Tasks

Preview Give feedback

1. Move "experimental" headers into main cuspatial include directory #1083
   improvement libcuspatial +2
   
2. Improve C++ header file organization #1080
   improvement libcuspatial +2
   
3. Improve C++ source file organization
4. Improve C++ test file organization
5. Improve C++ benchmark file organization

Is your feature request related to a problem? Please describe.
I think we should organize our headers and source better. To make implementations, tests, and benchmarks easier to find and navigate, I would like the directories of source files, tests, and benchmarks to match the names of the API header that they implement. Currently this is not strictly true. Here is the current include tree (ignoring experimental directory)

include
├── cuspatial
│   ├── constants.hpp
│   ├── coordinate_transform.hpp
│   ├── cubic_spline.hpp
│   ├── cuda_utils.hpp
│   ├── cusparse_error.hpp
│   ├── detail
│   │   ├── cubic_spline.hpp
│   │   ├── iterator.hpp
│   │   ├── nvtx
│   │   │   ├── nvtx3.hpp
│   │   │   └── ranges.hpp
│   │   └── utility
│   │       ├── device_atomics.cuh
│   │       ├── linestring.cuh
│   │       └── traits.hpp
│   ├── distances
│   │   └── linestring_distance.hpp
│   ├── error.hpp
│   ├── hausdorff.hpp
│   ├── haversine.hpp
│   ├── point_in_polygon.hpp
│   ├── point_quadtree.hpp
│   ├── polygon_bounding_box.hpp
│   ├── polyline_bounding_box.hpp
│   ├── shapefile_reader.hpp
│   ├── spatial_join.hpp
│   ├── spatial_window.hpp
│   ├── trajectory.hpp
│   └── vec_2d.hpp
└── doxygen_groups.h

Note that this is relatively flat -- algorithms are in top level headers, with the exception of linestring_distance.hpp. Another library that takes this flat approach is Thrust. It's nice that it's mostly easy to include things:

#include <thrust/gather.h>
#include <thrust/scan.h>
#include <thrust/device_vector.h>

Thrust iterators are an exception:

#include <thrust/iterator/transform_iterator.h>

There is a natural tradeoff between ease of including headers, and clutter when browsing the include directory. However, if there is a natural logical grouping of headers (as with Thrust iterators), then they can be grouped in directories. But this grouping can happen in many ways, and therefore leads to much bikeshedding with lots of discussion about noun-form group names vs. verb-form group names, as we experienced in #644.

cuspatial/cpp/src directory already does some of this grouping, which doesn't match the cuspatial/cpp/include directory at all:

src
├── indexing
│   └── construction
│       ├── detail
│       │   ├── phase_1.cuh
│       │   ├── phase_2.cuh
│       │   └── utilities.cuh
│       └── point_quadtree.cu
├── interpolate
│   └── cubic_spline.cu
├── io
│   └── shp
│       ├── polygon_shapefile_reader.cpp
│       └── polygon_shapefile_reader.cu
├── join
│   ├── detail
│   │   ├── intersection.cuh
│   │   ├── point.cuh
│   │   └── traversal.cuh
│   ├── quadtree_point_in_polygon.cu
│   ├── quadtree_point_to_nearest_polyline.cu
│   └── quadtree_poly_filtering.cu
├── spatial
│   ├── hausdorff.cu
│   ├── haversine.cu
│   ├── linestring_distance.cu
│   ├── lonlat_to_cartesian.cu
│   ├── point_in_polygon.cu
│   ├── polygon_bounding_box.cu
│   └── polyline_bounding_box.cu
├── spatial_window
│   └── spatial_window.cu
├── trajectory
│   ├── derive_trajectories.cu
│   ├── trajectory_bounding_boxes.cu
│   └── trajectory_distances_and_speeds.cu
└── utility
    ├── point_in_polygon.cuh
    ├── point_to_nearest_polyline.cuh
    ├── scatter_output_iterator.cuh
    ├── size_from_offsets.cuh
    └── z_order.cuh

I don't mind this, except for the "spatial" folder, which contains distance, projection, containment, and bounding algorithms. Then there is the "spatial_window" folder, which is apparently different from "spatial", but only has one file. (I think this should be called "filtering").

The "utility" directory seems to conflate the concept of "utility" (helper code generally reusable across modules) and "detail" (implementation details not intended for reuse).

Let the bikeshedding begin!

[isVoid]

Considering most our c++ primitives are 1-1 exposed to cuspatial python, perhaps we can try mirroring the cuspatial python taxonomy until something breaks?

Another elephant in the room is that when we merge experimental into the main library, where should these new header file go? I can see two one way:

• Keep cuh file, and leave the column API separate in .hpp file.

- Merge header only and column API, use a single .cuh file. (This would defeat our purpose of removing cudf dependency)