Apply suggestions from code review

Co-authored-by: kirkrodrigues <[email protected]>

Author: davidlion

README.md

@@ -4,25 +4,37 @@ An open-source C++ library developed and used at YScope.
 
 # Usage
 
-## Via CMake's `find_package`
-
 First, [build](#building) and [install](#installing) `ystdlib` onto your system. Then, in your
 project's `CMakeLists.txt`, add the following:
 
 ```cmake
-# If `BUILD_TESTING` is set, set `ystdlib_BUILD_TESTING` to an accepted `FALSE` class value to skip
-# building ystdlib's unit tests.
-# option(ystdlib_BUILD_TESTING "" OFF)
-# If ystdlib is not installed to a path that is searched by default, set `ystdlib_ROOT` to manually
-# specify the location.
-# set(ystdlib_ROOT "<PATH_TO_INSTALLATION>")
 find_package(ystdlib REQUIRED)
-target_link_libraries(<target_name> <link_options>
-    ystdlib::<lib_1> ystdlib::<lib_2> ... ystdlib::<lib_N>
-    # other libs...
+target_link_libraries(<target_name>
+    [<link-options>]
+    ystdlib::<lib_1>
+    [ystdlib::<lib_2> ... ystdlib::<lib_N>]
 )
 ```
 
+Where
+
+* `<target_name>` is the name of your target.
+* `<link-options>` are the link options for your target.
+* `lib_1`, `lib_2`, ..., `lib_N` are the names of the ystdlib libraries you wish to link with your
+  target.
+
+> [!NOTE]
+> If `BUILD_TESTING` is set, set `ystdlib_BUILD_TESTING` to an accepted `FALSE` class value to skip
+> building ystdlib's unit tests.
+
+> [!TIP]
+> If ystdlib is not installed to a path that is searched by default, set `ystdlib_ROOT` to manually
+> specify the location:
+> 
+> ```cmake
+> set(ystdlib_ROOT "<PATH_TO_INSTALLATION>")
+> ```
+
 # Contributing
 Follow the steps below to develop and contribute to the project.
 
@@ -46,7 +58,10 @@ task deps:install-all
 
 ## Building
 
-### Task
+The library can be built directly using [CMake](#using-cmake) or indirectly using
+[Task](#using-task).
+
+### Using Task
 
 To build all targets:
 ```shell
@@ -63,7 +78,7 @@ To build an executable containing a single library's unit tests:
 task build:unit-test-<lib_name>
 ```
 
-### CMake
+### Using CMake
 
 To build all libraries, run:
 
@@ -72,17 +87,19 @@ cmake -S . -B ./build
 cmake --build ./build
 ```
 
-To build a subset of libraries, set the variable `ystdlib_LIBRARIES` to a semicolon(`;`) separated
-list of library names. The library names match their [directory name in src/](./src/ystdlib).
-For example:
+To build a subset of libraries, set the variable `ystdlib_LIBRARIES` to a semicolon-separated (`;`)
+list of library names. The library names match their [directory name in src/](./src/ystdlib). For
+example:
 
 ```shell
 cmake -S . -B ./build -Dystdlib_LIBRARIES="containers;io_interface"
 cmake --build ./build
 ```
 
-It is not necessary to specify libraries your subset depends on. In the example, specifying
-`io_interface` automatically builds `wrapped_facade_headers`.
+> [!NOTE]
+> Internal dependencies of the libraries you choose will be automatically built, even if you don't
+> explicitly specify them. In the example, specifying `io_interface` automatically builds
+> `wrapped_facade_headers`.
 
 ## Installing
 

cmake/ystdlib-helpers.cmake

@@ -1,28 +1,29 @@
 include(CMakePackageConfigHelpers)
 
-# Checks that each argument name is defined and non-empty. Requires a prior call to
-# `cmake_parse_arguments` with `ARG` as the prefix to access the values of the arguments in
-# `REQUIRED_ARG_NAMES`.
+# Checks that each argument name in `REQUIRED_ARG_NAMES` is defined and non-empty. Assumes the
+# arguments are stored in variables prefixed with `ARG_<NAME>`.
 #
 # @param {string[]} REQUIRED_ARG_NAMES
 macro(require_argument_values REQUIRED_ARG_NAMES)
     set(_REQUIRED_ARGS "${REQUIRED_ARG_NAMES}")
     foreach(_REQUIRED_ARG IN LISTS _REQUIRED_ARGS)
         if(NOT DEFINED ARG_${_REQUIRED_ARG} OR ARG_${_REQUIRED_ARG} STREQUAL "")
-            message(FATAL_ERROR "Non-empty value for argument: '${_REQUIRED_ARG}'")
+            message(FATAL_ERROR "Empty value for argument: '${_REQUIRED_ARG}'")
         endif()
     endforeach()
 endmacro()
 
-# @param {string[]} SOURCE_LIST The list of source files to check.
-# @param {bool} IS_HEADER_ONLY Returns TRUE if list only contains header files, FALSE otherwise.
+# Checks if `SOURCE_LIST` contains only header files.
+#
+# @param {string[]} SOURCE_LIST
+# @param {bool} IS_HEADER_ONLY Returns whether the list contains only header files.
 # @param {string} NON_HEADER_FILE Returns the name of the first, if any, non-header file.
 function(check_if_header_only SOURCE_LIST IS_HEADER_ONLY NON_HEADER_FILE)
     set(LOCAL_SOURCE_LIST "${${SOURCE_LIST}}")
     foreach(SRC_FILE IN LISTS LOCAL_SOURCE_LIST)
-        if(NOT ${SRC_FILE} MATCHES ".*\\.(h|hpp)")
+        if(NOT "${SRC_FILE}" MATCHES ".*\\.(h|hpp)")
             set(${IS_HEADER_ONLY} FALSE PARENT_SCOPE)
-            set(${NON_HEADER_FILE} ${SRC_FILE} PARENT_SCOPE)
+            set(${NON_HEADER_FILE} "${SRC_FILE}" PARENT_SCOPE)
             return()
         endif()
     endforeach()
@@ -113,15 +114,15 @@ function(add_cpp_library)
     )
 endfunction()
 
-# Adds a C++ 20 test executable named unit-test-NAME that will be built with SOURCES and linked with
-# LINK_LIBRARIES, in addition to Catch2.
+# Adds a C++ 20 test executable named `unit-test-NAME` that will be built with `SOURCES` and linked
+# with `LINK_LIBRARIES`, in addition to Catch2.
 #
 # @param {string} NAME
 # @param {string} NAMESPACE
 # @param {string[]} SOURCES
 # @param {string[]} [LINK_LIBRARIES]
-# @param {string} [UNIFIED_TEST_TARGET] If set, SOURCES and LINK_LIBRARIES are also added to
-# UNIFIED_TEST_TARGET.
+# @param {string} [UNIFIED_TEST_TARGET] If set, `SOURCES` and `LINK_LIBRARIES` are also added to
+# `UNIFIED_TEST_TARGET`.
 function(add_catch2_tests)
     set(SINGLE_VALUE_ARGS
         NAME
@@ -177,11 +178,11 @@ endfunction()
 # @param {string} NAME
 # @param {string} NAMESPACE
 # @param {string} [CONFIG_DEST_DIR] Destination to install the generated config file
-# (NAME-config.cmake).
-# @param {string} [CONFIG_INPUT_DIR] configure_package_config_file input file
-# (NAME-config.cmake.in).
-# @param {string} [CONFIG_OUTPUT_DIR] configure_package_config_file output file
-# (NAME-config.cmake).
+# (`NAME-config.cmake`).
+# @param {string} [CONFIG_INPUT_DIR] `configure_package_config_file` input file
+# (`NAME-config.cmake.in`).
+# @param {string} [CONFIG_OUTPUT_DIR] `configure_package_config_file` output file
+# (`NAME-config.cmake`).
 function(install_library)
     set(SINGLE_VALUE_ARGS
         NAME

examples/README.md

@@ -1,32 +1,26 @@
 # Examples
 
+This directory contains example programs that demonstrate how to use the ystdlib library.
+
 The example program `linking-tests` references all of ystdlib's library targets to ensure they can
 be installed and linked correctly.
 
-## Building
-
-First, ensure ystdlib has been installed. For example, after
-[building ystdlib](../README.md#building), [install it](../README.md#installing) by running:
+# Requirements
 
-```shell
-cmake --install "./build" --prefix "./build/examples/ystdlib"
-```
+[Build](../README.md#building) and [install](../README.md#installing) ystdlib. The commands below
+assume you've built and installed ystdlib to `./build/examples/ystdlib`. If you installed it to a
+different location, adjust the paths accordingly.
 
-To build the examples, run:
+## Building
 
 ```shell
 cmake -S "./examples" -B "./build/examples" -Dystdlib_ROOT="./build/examples/ystdlib"
 
 cmake --build "./build/examples"
 ```
 
-Setting `ystdlib_ROOT` is not necessary if `ystdlib` is installed on a path CMake searches by
-default.
-
 ## Running
 
-Run the example program as follows:
-
 ```shell
 ./build/examples/linking-tests
 ```