docs: improvements to source code documentation (#1236)

src/platform/windows/misc.cpp

@@ -229,10 +229,10 @@ namespace platf {
   }
 
   /**
- * @brief A function to obtain the current sessions user's primary token with elevated privileges
- *
- * @return The users token, if user has admin capability it will be elevated. If not, it will return back a limited token. On error, nullptrs
- */
+   * @brief A function to obtain the current sessions user's primary token with elevated privileges
+   *
+   * @return The users token, if user has admin capability it will be elevated. If not, it will return back a limited token. On error, nullptrs
+   */
   HANDLE
   retrieve_users_token(bool elevated) {
     DWORD consoleSessionId;
@@ -430,15 +430,15 @@ namespace platf {
   }
 
   /**
- * @brief Creates a bp::child object from the results of launching a process
- *
- * @param process_launched A boolean indicating whether the launch was successful or not
- * @param cmd The command that was used to launch the process
- * @param ec A reference to an std::error_code object that will store any error that occurred during the launch
- * @param process_info A reference to a PROCESS_INFORMATION structure that contains information about the new process
- * @param group A pointer to a bp::group object that will add the new process to its group, if not null
- * @return A bp::child object representing the new process, or an empty bp::child object if the launch failed or an error occurred
- */
+   * @brief Creates a bp::child object from the results of launching a process
+   *
+   * @param process_launched A boolean indicating whether the launch was successful or not
+   * @param cmd The command that was used to launch the process
+   * @param ec A reference to an std::error_code object that will store any error that occurred during the launch
+   * @param process_info A reference to a PROCESS_INFORMATION structure that contains information about the new process
+   * @param group A pointer to a bp::group object that will add the new process to its group, if not null
+   * @return A bp::child object representing the new process, or an empty bp::child object if the launch failed or an error occurred
+   */
   bp::child
   create_boost_child_from_results(bool process_launched, const std::string &cmd, std::error_code &ec, PROCESS_INFORMATION &process_info, bp::group *group) {
     // Use RAII to ensure the process is closed when we're done with it, even if there was an error.
@@ -477,12 +477,12 @@ namespace platf {
   }
 
   /**
- * @brief Impersonate the current user, invoke the callback function, then returns back to system context.
- *
- * @param user_token A handle to the user's token that was obtained from the shell
- * @param callback A function that will be executed while impersonating the user
- * @return An std::error_code object that will store any error that occurred during the impersonation
- */
+   * @brief Impersonate the current user, invoke the callback function, then returns back to system context.
+   *
+   * @param user_token A handle to the user's token that was obtained from the shell
+   * @param callback A function that will be executed while impersonating the user
+   * @return An std::error_code object that will store any error that occurred during the impersonation
+   */
   std::error_code
   impersonate_current_user(HANDLE user_token, std::function<void()> callback) {
     std::error_code ec;
@@ -515,12 +515,12 @@ namespace platf {
   }
 
   /**
- * @brief A function to create a STARTUPINFOEXW structure for launching a process
- *
- * @param file A pointer to a FILE object that will be used as the standard output and error for the new process, or null if not needed
- * @param ec A reference to an std::error_code object that will store any error that occurred during the creation of the structure
- * @return A STARTUPINFOEXW structure that contains information about how to launch the new process
- */
+   * @brief A function to create a STARTUPINFOEXW structure for launching a process
+   *
+   * @param file A pointer to a FILE object that will be used as the standard output and error for the new process, or null if not needed
+   * @param ec A reference to an std::error_code object that will store any error that occurred during the creation of the structure
+   * @return A STARTUPINFOEXW structure that contains information about how to launch the new process
+   */
   STARTUPINFOEXW
   create_startup_info(FILE *file, std::error_code &ec) {
     // Initialize a zeroed-out STARTUPINFOEXW structure and set its size
@@ -563,23 +563,23 @@ namespace platf {
   }
 
   /**
- * @brief Runs a command on the users profile
- *
- * This function launches a child process as the user, using the current user's environment
- * and a specific working directory. If the launch is successful, a `bp::child` object representing the new
- * process is returned. Otherwise, an error code is returned.
- *
- * @param elevated Specify to elevate the process or not
- * @param interactive Specifies whether this will run in a window or hidden
- * @param cmd The command to run
- * @param working_dir The working directory for the new process
- * @param env The environment variables to use for the new process
- * @param file A file object to redirect the child process's output to (may be nullptr)
- * @param ec An error code, set to indicate any errors that occur during the launch process
- * @param group A pointer to a `bp::group` object to which the new process should belong (may be nullptr)
- *
- * @return A `bp::child` object representing the new process, or an empty `bp::child` object if the launch fails
- */
+   * @brief Runs a command on the users profile
+   *
+   * This function launches a child process as the user, using the current user's environment
+   * and a specific working directory. If the launch is successful, a `bp::child` object representing the new
+   * process is returned. Otherwise, an error code is returned.
+   *
+   * @param elevated Specify to elevate the process or not
+   * @param interactive Specifies whether this will run in a window or hidden
+   * @param cmd The command to run
+   * @param working_dir The working directory for the new process
+   * @param env The environment variables to use for the new process
+   * @param file A file object to redirect the child process's output to (may be nullptr)
+   * @param ec An error code, set to indicate any errors that occur during the launch process
+   * @param group A pointer to a `bp::group` object to which the new process should belong (may be nullptr)
+   *
+   * @return A `bp::child` object representing the new process, or an empty `bp::child` object if the launch fails
+   */
   bp::child
   run_command(bool elevated, bool interactive, const std::string &cmd, boost::filesystem::path &working_dir, bp::environment &env, FILE *file, std::error_code &ec, bp::group *group) {
     BOOL ret;
@@ -1091,4 +1091,4 @@ namespace platf {
     }
     return {};
   }
-}  // namespace platf
+}  // namespace platf