Merge pull request #7972 from Robyt3/Base-Documentation-Shell-OS-etc

Document all shell, OS, secure random and related functions

src/base/system.h

@@ -2068,36 +2068,6 @@ int net_would_block();
 
 int net_socket_read_wait(NETSOCKET sock, int time);
 
-/*
-	Function: open_link
-		Opens a link in the browser.
-
-	Parameters:
-		link - The link to open in a browser.
-
-	Returns:
-		Returns 1 on success, 0 on failure.
-
-	Remarks:
-		This may not be called with untrusted input or it'll result in arbitrary code execution, especially on Windows.
-*/
-int open_link(const char *link);
-
-/*
-	Function: open_file
-		Opens a file or directory with default program.
-
-	Parameters:
-		path - The path to open.
-
-	Returns:
-		Returns 1 on success, 0 on failure.
-
-	Remarks:
-		This may not be called with untrusted input or it'll result in arbitrary code execution, especially on Windows.
-*/
-int open_file(const char *path);
-
 /**
  * Swaps the endianness of data. Each element is swapped individually by reversing its bytes.
  *
@@ -2474,165 +2444,246 @@ unsigned bytes_be_to_uint(const unsigned char *bytes);
  */
 void uint_to_bytes_be(unsigned char *bytes, unsigned value);
 
-/*
+/**
-	Function: pid
+ * @defgroup Shell
-		Returns the pid of the current process.
+ * Shell, process management, OS specific functionality.
+ */
 
-	Returns:
+/**
-		pid of the current process
+ * Returns the ID of the current process.
-*/
+ *
+ * @ingroup Shell
+ *
+ * @return PID of the current process.
+ */
 int pid();
 
-/*
+/**
-	Function: cmdline_fix
+ * Fixes the command line arguments to be encoded in UTF-8 on all systems.
-		Fixes the command line arguments to be encoded in UTF-8 on all
+ *
-		systems.
+ * @ingroup Shell
-
+ *
-	Parameters:
+ * @param argc A pointer to the argc parameter that was passed to the main function.
-		argc - A pointer to the argc parameter that was passed to the main function.
+ * @param argv A pointer to the argv parameter that was passed to the main function.
-		argv - A pointer to the argv parameter that was passed to the main function.
+ *
-
+ * @remark You need to call @link cmdline_free @endlink once you're no longer using the results.
-	Remarks:
+ */
-		- You need to call cmdline_free once you're no longer using the
-		results.
-*/
 void cmdline_fix(int *argc, const char ***argv);
 
-/*
+/**
-	Function: cmdline_free
+ * Frees memory that was allocated by @link cmdline_fix @endlink.
-		Frees memory that was allocated by cmdline_fix.
+ *
-
+ * @ingroup Shell
-	Parameters:
+ *
-		argc - The argc obtained from cmdline_fix.
+ * @param argc The argc obtained from `cmdline_fix`.
-		argv - The argv obtained from cmdline_fix.
+ * @param argv The argv obtained from `cmdline_fix`.
-
+ */
-*/
 void cmdline_free(int argc, const char **argv);
 
 #if defined(CONF_FAMILY_WINDOWS)
+/**
+ * A handle for a process.
+ *
+ * @ingroup Shell
+ */
 typedef void *PROCESS;
+/**
+ * A handle that denotes an invalid process.
+ *
+ * @ingroup Shell
+ */
 constexpr PROCESS INVALID_PROCESS = nullptr;
 #else
+/**
+ * A handle for a process.
+ *
+ * @ingroup Shell
+ */
 typedef pid_t PROCESS;
+/**
+ * A handle that denotes an invalid process.
+ *
+ * @ingroup Shell
+ */
 constexpr PROCESS INVALID_PROCESS = 0;
 #endif
 
+/**
+ * Determines the initial window state when using @link shell_execute @endlink
+ * to execute a process.
+ *
+ * @ingroup Shell
+ *
+ * @remark Currently only supported on Windows.
+ */
 enum class EShellExecuteWindowState
 {
+	/**
+	 * The process window is opened in the foreground and activated.
+	 */
 	FOREGROUND,
+
+	/**
+	 * The process window is opened in the background without focus.
+	 */
 	BACKGROUND,
 };
 
 /**
  * Executes a given file.
  *
+ * @ingroup Shell
+ *
  * @param file The file to execute.
  * @param window_state The window state how the process window should be shown.
  *
- * @return Handle of the new process, or `INVALID_PROCESS` on error.
+ * @return Handle of the new process, or @link INVALID_PROCESS @endlink on error.
  */
 PROCESS shell_execute(const char *file, EShellExecuteWindowState window_state);
 
 /**
  * Sends kill signal to a process.
  *
+ * @ingroup Shell
+ *
  * @param process Handle of the process to kill.
  *
- * @return 1 on success, 0 on error.
+ * @return `1` on success, `0` on error.
  */
 int kill_process(PROCESS process);
 
 /**
  * Checks if a process is alive.
  *
+ * @ingroup Shell
+ *
  * @param process Handle/PID of the process.
  *
- * @return bool Returns true if the process is currently running, false if the process is not running (dead).
+ * @return `true` if the process is currently running,
+ * `false` if the process is not running (dead).
  */
 bool is_process_alive(PROCESS process);
 
-/*
+/**
-	Function: generate_password
+ * Opens a link in the browser.
-		Generates a null-terminated password of length `2 *
+ *
-		random_length`.
+ * @ingroup Shell
+ *
+ * @param link The link to open in a browser.
+ *
+ * @return `1` on success, `0` on failure.
+ *
+ * @remark The strings are treated as zero-terminated strings.
+ * @remark This may not be called with untrusted input or it'll result in arbitrary code execution, especially on Windows.
+ */
+int open_link(const char *link);
 
-	Parameters:
+/**
-		buffer - Pointer to the start of the output buffer.
+ * Opens a file or directory with default program.
-		length - Length of the buffer.
+ *
-		random - Pointer to a randomly-initialized array of shorts.
+ * @ingroup Shell
-		random_length - Length of the short array.
+ *
-*/
+ * @param path The path to open.
+ *
+ * @return `1` on success, `0` on failure.
+ *
+ * @remark The strings are treated as zero-terminated strings.
+ * @remark This may not be called with untrusted input or it'll result in arbitrary code execution, especially on Windows.
+ */
+int open_file(const char *path);
+
+/**
+ * @defgroup Secure-Random
+ * Secure random number generation.
+ */
+
+/**
+ * Generates a null-terminated password of length `2 * random_length`.
+ *
+ * @ingroup Secure-Random
+ *
+ * @param buffer Pointer to the start of the output buffer.
+ * @param length Length of the buffer.
+ * @param random Pointer to a randomly-initialized array of shorts.
+ * @param random_length Length of the short array.
+ */
 void generate_password(char *buffer, unsigned length, const unsigned short *random, unsigned random_length);
 
-/*
+/**
-	Function: secure_random_init
+ * Initializes the secure random module.
-		Initializes the secure random module.
+ * You *MUST* check the return value of this function.
-		You *MUST* check the return value of this function.
+ *
-
+ * @ingroup Secure-Random
-	Returns:
+ *
-		0 - Initialization succeeded.
+ * @return `0` on success.
-		1 - Initialization failed.
+ */
-*/
 int secure_random_init();
 
-/*
+/**
-	Function: secure_random_uninit
+ * Uninitializes the secure random module.
-		Uninitializes the secure random module.
+ *
-
+ * @ingroup Secure-Random
-	Returns:
+ *
-		0 - Uninitialization succeeded.
+ * @return `0` on success.
-		1 - Uninitialization failed.
+ */
-*/
 int secure_random_uninit();
 
-/*
+/**
-	Function: secure_random_password
+ * Fills the buffer with the specified amount of random password characters.
-		Fills the buffer with the specified amount of random password
+ *
-		characters.
+ * @ingroup Secure-Random
-
+ *
-		The desired password length must be greater or equal to 6, even
+ * @param buffer Pointer to the start of the buffer.
-		and smaller or equal to 128.
+ * @param length Length of the buffer.
-
+ * @param pw_length Length of the desired password.
-	Parameters:
+ *
-		buffer - Pointer to the start of the buffer.
+ * @remark The desired password length must be greater or equal to 6,
-		length - Length of the buffer.
+ * even and smaller or equal to 128.
-		pw_length - Length of the desired password.
+ */
-*/
 void secure_random_password(char *buffer, unsigned length, unsigned pw_length);
 
-/*
+/**
-	Function: secure_random_fill
+ * Fills the buffer with the specified amount of random bytes.
-		Fills the buffer with the specified amount of random bytes.
+ *
-
+ * @ingroup Secure-Random
-	Parameters:
+ *
-		buffer - Pointer to the start of the buffer.
+ * @param buffer Pointer to the start of the buffer.
-		length - Length of the buffer.
+ * @param length Length of the buffer.
-*/
+ */
 void secure_random_fill(void *bytes, unsigned length);
 
-/*
+/**
-	Function: secure_rand
+ * Returns random `int`.
-		Returns random int (replacement for rand()).
+ *
-*/
+ * @ingroup Secure-Random
+ *
+ * @return Random int.
+ *
+ * @remark Can be used as a replacement for the `rand` function.
+ */
 int secure_rand();
 
-/*
+/**
-	Function: secure_rand_below
+ * Returns a random nonnegative integer below the given number,
-		Returns a random nonnegative integer below the given number,
+ * with a uniform distribution.
-		with a uniform distribution.
+ *
-
+ * @ingroup Secure-Random
-	Parameters:
+ *
-		below - Upper limit (exclusive) of integers to return.
+ * @param below Upper limit (exclusive) of integers to return.
-*/
+ *
+ * @return Random nonnegative below the given number.
+ */
 int secure_rand_below(int below);
 
 /**
  * Returns a human-readable version string of the operating system.
  *
+ * @ingroup Shell
+ *
  * @param version Buffer to use for the output.
  * @param length Length of the output buffer.
  *
- * @return true on success, false on failure.
+ * @return `true` on success, `false` on failure.
  */
 bool os_version_str(char *version, size_t length);
 
@@ -2643,6 +2694,8 @@ bool os_version_str(char *version, size_t length);
  * If the preferred locale could not be determined this function
  * falls back to the locale `"en-US"`.
  *
+ * @ingroup Shell
+ *
  * @param locale Buffer to use for the output.
  * @param length Length of the output buffer.
  *
@@ -2651,7 +2704,25 @@ bool os_version_str(char *version, size_t length);
 void os_locale_str(char *locale, size_t length);
 
 #if defined(CONF_EXCEPTION_HANDLING)
+/**
+ * @defgroup Exception-Handling
+ * Exception handling (crash logging).
+ */
+
+/**
+ * Initializes the exception handling module.
+ *
+ * @ingroup Exception-Handling
+ */
 void init_exception_handler();
+
+/**
+ * Sets the filename for writing the crash log.
+ *
+ * @ingroup Exception-Handling
+ *
+ * @param log_file_path Absolute path to which crash log file should be written.
+ */
 void set_exception_handler_log_file(const char *log_file_path);
 #endif
 
@@ -2668,7 +2739,9 @@ int net_socket_read_wait(NETSOCKET sock, std::chrono::nanoseconds nanoseconds);
 
 /**
  * Fixes the command line arguments to be encoded in UTF-8 on all systems.
- * This is a RAII wrapper for cmdline_fix and cmdline_free.
+ * This is a RAII wrapper for @link cmdline_fix @endlink and @link cmdline_free @endlink.
+ *
+ * @ingroup Shell
  */
 class CCmdlineFix
 {
@@ -2690,25 +2763,29 @@ public:
 
 #if defined(CONF_FAMILY_WINDOWS)
 /**
- * Converts a utf8 encoded string to a wide character string
+ * Converts a UTF-8 encoded string to a wide character string
  * for use with the Windows API.
  *
- * @param str The utf8 encoded string to convert.
+ * @ingroup Shell
+ *
+ * @param str The UTF-8 encoded string to convert.
  *
  * @return The argument as a wide character string.
  *
  * @remark The argument string must be zero-terminated.
- * @remark Fails with assertion error if passed utf8 is invalid.
+ * @remark Fails with assertion error if passed UTF-8 is invalid.
  */
 std::wstring windows_utf8_to_wide(const char *str);
 
 /**
  * Converts a wide character string obtained from the Windows API
- * to a utf8 encoded string.
+ * to a UTF-8 encoded string.
+ *
+ * @ingroup Shell
  *
  * @param wide_str The wide character string to convert.
  *
- * @return The argument as a utf8 encoded string, wrapped in an optional.
+ * @return The argument as a UTF-8 encoded string, wrapped in an optional.
  * The optional is empty, if the wide string contains invalid codepoints.
  *
  * @remark The argument string must be zero-terminated.
@@ -2717,10 +2794,13 @@ std::optional<std::string> windows_wide_to_utf8(const wchar_t *wide_str);
 
 /**
  * This is a RAII wrapper to initialize/uninitialize the Windows COM library,
- * which may be necessary for using the open_file and open_link functions.
+ * which may be necessary for using the @link open_file @endlink and
+ * @link open_link @endlink functions.
  * Must be used on every thread. It's automatically used on threads created
- * with thread_init. Pass true to the constructor on threads that own a
+ * with @link thread_init @endlink. Pass `true` to the constructor on threads
- * window (i.e. pump a message queue).
+ * that own a window (i.e. pump a message queue).
+ *
+ * @ingroup Shell
  */
 class CWindowsComLifecycle
 {
@@ -2736,11 +2816,11 @@ public:
  *
  * @param protocol_name The name of the protocol.
  * @param executable The absolute path of the executable that will be associated with the protocol.
- * @param updated Pointer to a variable that will be set to true, iff the shell needs to be updated.
+ * @param updated Pointer to a variable that will be set to `true`, iff the shell needs to be updated.
  *
- * @return true on success, false on failure.
+ * @return `true` on success, `false` on failure.
  *
- * @remark The caller must later call shell_update, iff the shell needs to be updated.
+ * @remark The caller must later call @link shell_update @endlink, iff the shell needs to be updated.
  */
 bool shell_register_protocol(const char *protocol_name, const char *executable, bool *updated);
 
@@ -2753,11 +2833,11 @@ bool shell_register_protocol(const char *protocol_name, const char *executable,
  * @param description A readable description for the file extension.
  * @param executable_name A unique name that will used to describe the application.
  * @param executable The absolute path of the executable that will be associated with the file extension.
- * @param updated Pointer to a variable that will be set to true, iff the shell needs to be updated.
+ * @param updated Pointer to a variable that will be set to `true`, iff the shell needs to be updated.
  *
- * @return true on success, false on failure.
+ * @return `true` on success, `false` on failure.
  *
- * @remark The caller must later call shell_update, iff the shell needs to be updated.
+ * @remark The caller must later call @link shell_update @endlink, iff the shell needs to be updated.
  */
 bool shell_register_extension(const char *extension, const char *description, const char *executable_name, const char *executable, bool *updated);
 
@@ -2768,11 +2848,11 @@ bool shell_register_extension(const char *extension, const char *description, co
  *
  * @param name Readable name of the application.
  * @param executable The absolute path of the executable being registered.
- * @param updated Pointer to a variable that will be set to true, iff the shell needs to be updated.
+ * @param updated Pointer to a variable that will be set to `true`, iff the shell needs to be updated.
  *
- * @return true on success, false on failure.
+ * @return `true` on success, `false` on failure.
  *
- * @remark The caller must later call shell_update, iff the shell needs to be updated.
+ * @remark The caller must later call @link shell_update @endlink, iff the shell needs to be updated.
  */
 bool shell_register_application(const char *name, const char *executable, bool *updated);
 
@@ -2784,11 +2864,11 @@ bool shell_register_application(const char *name, const char *executable, bool *
  * @param shell_class The shell class to delete.
  * For protocols this is the name of the protocol.
  * For file extensions this is the program ID associated with the file extension.
- * @param updated Pointer to a variable that will be set to true, iff the shell needs to be updated.
+ * @param updated Pointer to a variable that will be set to `true`, iff the shell needs to be updated.
  *
- * @return true on success, false on failure.
+ * @return `true` on success, `false` on failure.
  *
- * @remark The caller must later call shell_update, iff the shell needs to be updated.
+ * @remark The caller must later call @link shell_update @endlink, iff the shell needs to be updated.
  */
 bool shell_unregister_class(const char *shell_class, bool *updated);
 
@@ -2798,11 +2878,11 @@ bool shell_unregister_class(const char *shell_class, bool *updated);
  * @ingroup Shell
  *
  * @param executable The absolute path of the executable being unregistered.
- * @param updated Pointer to a variable that will be set to true, iff the shell needs to be updated.
+ * @param updated Pointer to a variable that will be set to `true`, iff the shell needs to be updated.
  *
- * @return true on success, false on failure.
+ * @return `true` on success, `false` on failure.
  *
- * @remark The caller must later call shell_update, iff the shell needs to be updated.
+ * @remark The caller must later call @link shell_update @endlink, iff the shell needs to be updated.
  */
 bool shell_unregister_application(const char *executable, bool *updated);