read_env_file[_inline]: documentation comment

Author: davmac314

src/dinit-env.cc

@@ -17,7 +17,16 @@ static void log_bad_env_cmd(int linenum)
     log(loglevel_t::ERROR, "Unknown command in environment file (line ", linenum, ")");
 }
 
-// Read and set environment variables from a file. May throw std::bad_alloc, std::system_error.
+// Read and set environment variables (encapsulated in an 'environment' object) from a file.
+// File contains "VAR=VALUE" assignments (line by line) and "!" meta-commands.
+// Parameters:
+//   env_file_path - the path to the environment file to process
+//   log_warnings - whether warnings should be logged (eg about invalid embedded commands)
+//   env - the environment to modify
+//   throw_on_open_failure - whether to throw an exception on failure to open the specified
+//                           file. If false, returns instead (without logging failure).
+// Throws:
+//   std::bad_alloc, std::system_error
 void read_env_file(const char *env_file_path, bool log_warnings, environment &env, bool throw_on_open_failure)
 {
     read_env_file_inline(env_file_path, log_warnings, env, throw_on_open_failure, log_bad_env, log_bad_env_cmd);

src/includes/dinit-env.h

@@ -353,7 +353,18 @@ class environment
     }
 };
 
-// Read and set environment variables from a file. May throw std::bad_alloc, std::system_error.
+// Read and set environment variables (encapsulated in an 'environment' object) from a file.
+// File contains "VAR=VALUE" assignments (line by line) and "!" meta-commands.
+// Parameters:
+//   env_file_path - the path to the environment file to process
+//   log_warnings - whether warnings should be logged (eg about invalid embedded commands)
+//   env - the environment to modify
+//   throw_on_open_failure - whether to throw an exception on failure to open the specified
+//                           file. If false, returns instead (without logging failure).
+//   log_inv_setting - function/functor to log invalid lines
+//   log_bad_cmd - function/functor to log bad meta commands
+// Throws:
+//   std::bad_alloc, std::system_error
 template <typename LOG_INV_SETTING, typename LOG_BAD_COMMAND>
 inline void read_env_file_inline(const char *env_file_path, bool log_warnings, environment &env,
         bool throw_on_open_failure, LOG_INV_SETTING &log_inv_setting, LOG_BAD_COMMAND &log_bad_cmd)