expand some source comments

CMakeLists.txt

@@ -44,18 +44,14 @@ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
 endif()
 
 # use HDF5
-option (SPINER_USE_HDF "Pull in hdf5" OFF)
+# This option defaults ON, as it's the most common
+# use-case
+option (SPINER_USE_HDF "Use HDF5 for I/O" ON)
 # use Kokkos offloading in tests
 option (SPINER_TEST_USE_KOKKOS "Use kokkos offloading for tests" OFF)
 option (SPINER_TEST_USE_KOKKOS_CUDA "Use kokkos cuda offloading for tests" OFF)
 
-# These didn't behave like I expected.
-# TODO: fix
-# include(CMakeDependentOption)
-# cmake_dependent_option (SPINER_TEST_USE_KOKKOS "Pull in Kokkos" OFF "BUILD_TESTING" OFF)
-# cmake_dependent_option (SPINER_TEST_USE_KOKKOS_CUDA "Use the Kokkos cuda backend" OFF "SPINER_TEST_USE_KOKKOS" OFF)
-
-# CTEST
+# CTest
 include(CTest)
 
 # clang format
@@ -71,6 +67,8 @@ add_library(spiner::spiner ALIAS spiner)
 
 include(FetchContent)
 
+# If we are on version 3.24+, then set FetchContent to always try 
+# to `find_package` before trying a download method
 if (CMAKE_VERSION VERSION_GREATER_EQUAL "3.24.0")
   set(FETCHCONTENT_TRY_FIND_PACKAGE_MODE ALWAYS)
   message(STATUS "FetchContent routines will try `find_package` first")
@@ -85,6 +83,7 @@ endif()
 
 set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_LIST_DIR}/cmake)
 
+# content is a wrapper to `FetchContent` calls
 include(content)
 spiner_content_declare(ports-of-call
   NAMESPACE spinerDeps
@@ -109,6 +108,9 @@ spiner_content_populate(
   NAMESPACE spinerDeps
 )
 
+# We don't know about this until HDF5 is 
+# populated, so we need to delay until it's been
+# (NB: newer versions of HDF5/CMake appear to fix this)
 if(HDF5_IS_PARALLEL)
   spiner_content_declare(MPI
     NO_FETCH

cmake/content.cmake

@@ -9,6 +9,43 @@ include(FetchContent)
 
 # Constructs `FetchContent_Declare` call, and records information
 # for popluation and linking
+# 
+# ::Overview
+#   With `[email protected]` and higher, the functionality of `FetchContent_` has
+#   been updated to provide the capability to try a `find_package` at the
+#   content population stage. This allows for the flexibility provided by 
+#   `FetchContent_` to easily coexist with the dependency configuration
+#   provided by `find_package`. Some benefits include:
+#   - automated fetching of content if it is unavailable
+#   - content population at configure. This allows for a package import
+#     to utilize `find_package()` or `add_subdirectory()` operations
+#   - local clones can be given priority with `FETCHCONTENT_SOURCE_DIR_<uppercaseName>`,
+#     which lets developers use dependencies explicitly in-tree
+#   The case where i.) the content or dependency is unavailable or ii.) it cannot
+#   be fetched (due, for example, to a failure of a download step) is an 
+#   unavoidable error.
+#
+#   As this cmake version is relatively fresh, we also want to provide a bridge
+#   to downstream code that still is pinned to an earlier releases of `cmake`. 
+#   To that end, these macros provide for replicating the main features introduced 
+#   to `FetchContent_` in `[email protected]`. Future releases of `spiner` will require 
+#   a minimum of `[email protected]`.
+#
+# :: Arguments 
+#   pkg_name - the name of the package or content. usually the argument to `find_package(<pkg_name>)`
+#   options:
+#   - NO_FETCH - disables all download steps. If `find_package(<pkg_name>)` fails, produce an error
+#   single_value:
+#   - GIT_REPO - the URL of the git repository to clone, if necessary
+#   - GIT_TAG  - the tag or commit to use 
+#   - NAMESPACE - prefix book-keeping variables with this
+#   multi_value:
+#   - COMPONENTS - specify required components of <pkg_name>. same as used in to `find_package`
+#   - EXPECTED_TARGETS - a list of targets that expected at population.
+#                       if these targets are not available after the population stage, an error is produced. 
+#                       if not specified, will default to `<pkg_name>::<pkg_name>`
+#   - ENABLE_OPTS - a list of cache vars used to configure content that is imported using `add_subdirectory()`
+#
 macro(spiner_content_declare pkg_name)
   set(options
     NO_FETCH
@@ -80,6 +117,15 @@ macro(spiner_content_declare pkg_name)
 
 endmacro()
 
+#
+# :: Overview
+#   This macro wraps a call to `FetchContent_MakeAvailable`.
+#   If we are using a `cmake` prior to 3.24, explicitly do a 
+#   `find_package()` with the declared options 
+# :: Arguments 
+#   single_value:
+#   - NAMESPACE - the namespace used in the corrisponding `spiner_content_declare` call
+#
 macro(spiner_content_populate)
   set(options)
   set(one_value_args