docs(src): add examples alias and general cleanup (#2763)

src/file_handler.cpp

@@ -1,6 +1,6 @@
 /**
  * @file file_handler.cpp
- * @brief File handling functions.
+ * @brief Definitions for file handling functions.
  */
 
 // standard includes
@@ -12,11 +12,6 @@
 #include "logging.h"
 
 namespace file_handler {
-  /**
-   * @brief Get the parent directory of a file or directory.
-   * @param path The path of the file or directory.
-   * @return `std::string` : The parent directory.
-   */
   std::string
   get_parent_directory(const std::string &path) {
     // remove any trailing path separators
@@ -29,11 +24,6 @@ namespace file_handler {
     return p.parent_path().string();
   }
 
-  /**
-   * @brief Make a directory.
-   * @param path The path of the directory.
-   * @return `bool` : `true` on success, `false` on failure.
-   */
   bool
   make_directory(const std::string &path) {
     // first, check if the directory already exists
@@ -44,16 +34,6 @@ namespace file_handler {
     return std::filesystem::create_directories(path);
   }
 
-  /**
-   * @brief Read a file to string.
-   * @param path The path of the file.
-   * @return `std::string` : The contents of the file.
-   *
-   * EXAMPLES:
-   * ```cpp
-   * std::string contents = read_file("path/to/file");
-   * ```
-   */
   std::string
   read_file(const char *path) {
     if (!std::filesystem::exists(path)) {
@@ -65,17 +45,6 @@ namespace file_handler {
     return std::string { (std::istreambuf_iterator<char>(in)), std::istreambuf_iterator<char>() };
   }
 
-  /**
-   * @brief Writes a file.
-   * @param path The path of the file.
-   * @param contents The contents to write.
-   * @return `int` : `0` on success, `-1` on failure.
-   *
-   * EXAMPLES:
-   * ```cpp
-   * int write_status = write_file("path/to/file", "file contents");
-   * ```
-   */
   int
   write_file(const char *path, const std::string_view &contents) {
     std::ofstream out(path);