[DOC] Add comments

CMakeLists.txt

@@ -5,30 +5,42 @@
 cmake_minimum_required (VERSION 3.25)
 
 # Define the application name and version.
-project (app-template VERSION 1.0.0)
+project (app-template
+         LANGUAGES CXX
+         VERSION 1.0.0
+         DESCRIPTION "My application description"
+)
 
-# Allow to include CMake scripts from the app-template.
+# This allows including `*.cmake` files from the `cmake` directory without specifying the full path.
 list (APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/cmake")
 
-# Use ccache.
+# Use ccache if available. This speeds up the build process by caching files that have been compiled before.
 include (ccache)
 
-# Specify the directories where to store the built archives, libraries and executables
+# Specify the directories where to store the built archives, libraries and executables.
 include (output_directories)
 
 # Add packages.
+# We use CPM for package management: https://github.com/cpm-cmake/CPM.cmake
+# The added packages (hibf, sharg, seqan3) are defined in the `cmake/package-locj.cmake` file.
 include (CPM)
 CPMUsePackageLock (${CMAKE_CURRENT_LIST_DIR}/cmake/package-lock.cmake)
 
 CPMGetPackage (hibf)
 CPMGetPackage (sharg)
 CPMGetPackage (seqan3)
 
+# Add the application. This will include `src/CMakeLists.txt`.
 add_subdirectory (src)
 
-## TEST
+# An option to disable configuring and building the tests. Tests are enabled by default.
+# If your project-name (line 8 of this file) is `app-template`, the option will be `app-template_TEST`.
+# It can be used when calling CMake: `cmake .. -Dapp-template_TEST=OFF`.
+# It is good practice to allow disabling tests. If another project includes your application,
+# it might not want to build your tests.
 option (${PROJECT_NAME}_TEST "Enable testing for ${PROJECT_NAME}." ON)
 
 if (${PROJECT_NAME}_TEST)
+    # Add the tests. This will include `test/CMakeLists.txt`.
     add_subdirectory (test EXCLUDE_FROM_ALL)
 endif ()

test/CMakeLists.txt

@@ -4,7 +4,11 @@
 
 cmake_minimum_required (VERSION 3.25)
 
+# This includes `cmake/test/config.cmake` which takes care of setting up the test infrastructure. It also provides
+# the `add_app_test` macro, which is used to add tests to the CMake test suite.
 include (test/config)
+
+# This includes `test/data/datasources.cmake`, which makes test data available to the tests.
 include (data/datasources.cmake)
 
 add_app_test (api_fastq_coversion_test.cpp)

test/data/README.md

@@ -8,4 +8,4 @@ SPDX-License-Identifier: CC0-1.0
 
 Store the data here that should be used as input files for the tests.
 Large files (>50kb) should not be stored here, but rather fetched from a webserver.
-Register each file (from external or internal storage) in the `datasources.cmake` file.
+Each file that is fetched from a webserver must be registered in the `datasources.cmake` file.

test/data/datasources.cmake

@@ -2,13 +2,32 @@
 # SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
 # SPDX-License-Identifier: CC0-1.0
 
+# This includes `cmake/test/declare_datasource.cmake`, which provides the `declare_datasource` function.
 include (test/declare_datasource)
 
-# Makes all files in this directory available to the build, i.e., copying them to <build>/data/.
+# Makes all files in this directory and subdirectories available to the build, i.e., copying them to <build>/data/.
+# `datasources.cmake`, `README.md`, and files ending in `.license` are ignored.
+# You may organise your data in subdirectories, but each file must have a unique name.
 include (test/add_local_data)
 
-# Downloads the to <build>/data/downloaded.fasta
-declare_datasource (FILE downloaded.fasta
+# Downloads the file to <build>/data/downloaded.fasta
+# The checksum of the downloaded file is checked to ensure that:
+# * The download was not corrupted.
+# * The file was not tampered with.
+#
+# Some ways to obtain the checksum:
+#
+#   wget --quiet -O- https://ftp.seqan.de/app-template/downloaded.fasta | sha256sum
+#   c3cb990ca1a25c7e31be3c6c2d009238d9ac9a44b2b7c143753c1e2881699077  -
+#   ^------------------------- checksum ---------------------------^  ^ file (- is stdin, the file was piped)
+#
+# You can also use curl:
+#   curl --silent https://ftp.seqan.de/app-template/downloaded.fasta | sha256sum
+#
+# If you have the file locally, you can use `sha256sum` directly:
+#   sha256sum downloaded.fasta
+#   c3cb990ca1a25c7e31be3c6c2d009238d9ac9a44b2b7c143753c1e2881699077  downloaded.fasta
+declare_datasource (FILE downloaded.fasta # This is a custom name. It does not have to match the file name.
                     URL https://ftp.seqan.de/app-template/downloaded.fasta
                     URL_HASH SHA256=c3cb990ca1a25c7e31be3c6c2d009238d9ac9a44b2b7c143753c1e2881699077
 )