diff --git a/Doxyfile b/Doxyfile index 690ddc5b166..9585a6d35e5 100644 --- a/Doxyfile +++ b/Doxyfile @@ -2257,7 +2257,7 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = +PREDEFINED = CONF_FAMILY_UNIX CONF_MYSQL CONF_DISCORD CONF_OPENSSL CONF_UPNP CONF_VIDEORECORDER CONF_ANTIBOT # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The diff --git a/src/base/system.h b/src/base/system.h index 9793204cafd..d9acf512dc5 100644 --- a/src/base/system.h +++ b/src/base/system.h @@ -1050,433 +1050,401 @@ int net_tcp_send(NETSOCKET sock, const void *data, int size); */ int net_tcp_recv(NETSOCKET sock, void *data, int maxsize); -/* - Function: net_tcp_close - Closes a TCP socket. - - Parameters: - sock - Socket to close. - - Returns: - Returns 0 on success. Negative value on failure. -*/ +/** + * Closes a TCP socket. + * + * @ingroup Network-TCP + * + * @param sock Socket to close. + * + * @return 0 on success. Negative value on failure. + */ int net_tcp_close(NETSOCKET sock); #if defined(CONF_FAMILY_UNIX) -/* Group: Network Unix Sockets */ - -/* - Function: net_unix_create_unnamed - Creates an unnamed unix datagram socket. +/** + * @defgroup Network-Unix-Sockets + * @ingroup Network-General + */ - Returns: - On success it returns a handle to the socket. On failure it returns -1. -*/ +/** + * Creates an unnamed unix datagram socket. + * + * @ingroup Network-Unix-Sockets + * + * @return On success it returns a handle to the socket. On failure it returns -1. + */ UNIXSOCKET net_unix_create_unnamed(); -/* - Function: net_unix_send - Sends data to a Unix socket. - - Parameters: - sock - Socket to use. - addr - Where to send the packet. - data - Pointer to the packet data to send. - size - Size of the packet. - - Returns: - Number of bytes sent. Negative value on failure. -*/ +/** + * Sends data to a Unix socket. + * + * @ingroup Network-Unix-Sockets + * + * @param sock Socket to use. + * @param addr Where to send the packet. + * @param data Pointer to the packet data to send. + * @param size Size of the packet. + * + * @return Number of bytes sent. Negative value on failure. + */ int net_unix_send(UNIXSOCKET sock, UNIXSOCKETADDR *addr, void *data, int size); -/* - Function: net_unix_set_addr - Sets the unixsocketaddress for a path to a socket file. - - Parameters: - addr - Pointer to the addressstruct to fill. - path - Path to the (named) unix socket. -*/ +/** + * Sets the unixsocketaddress for a path to a socket file. + * + * @ingroup Network-Unix-Sockets + * + * @param addr Pointer to the addressstruct to fill. + * @param path Path to the (named) unix socket. + */ void net_unix_set_addr(UNIXSOCKETADDR *addr, const char *path); -/* - Function: net_unix_close - Closes a Unix socket. - - Parameters: - sock - Socket to close. -*/ +/** + * Closes a Unix socket. + * + * @ingroup Network-Unix-Sockets + * + * @param sock Socket to close. + */ void net_unix_close(UNIXSOCKET sock); #endif -/* Group: Strings */ - -/* - Function: str_append - Appends a string to another. - - Parameters: - dst - Pointer to a buffer that contains a string. - src - String to append. - dst_size - Size of the buffer of the dst string. +/** + * @defgroup Strings + * + * String related functions. + */ - Remarks: - - The strings are treated as zero-terminated strings. - - Guarantees that dst string will contain zero-termination. -*/ +/** + * Appends a string to another. + * + * @ingroup Strings + * + * @param dst Pointer to a buffer that contains a string. + * @param src String to append. + * @param dst_size Size of the buffer of the dst string. + * + * @remark The strings are treated as zero-terminated strings. + * @remark Guarantees that dst string will contain zero-termination. + */ void str_append(char *dst, const char *src, int dst_size); -/* - Function: str_copy - Copies a string to another. - - Parameters: - dst - Pointer to a buffer that shall receive the string. - src - String to be copied. - dst_size - Size of the buffer dst. - - Remarks: - - The strings are treated as zero-terminated strings. - - Guarantees that dst string will contain zero-termination. -*/ +/** + * Copies a string to another. + * + * @ingroup Strings + * + * @param dst Pointer to a buffer that shall receive the string. + * @param src String to be copied. + * @param dst_size Size of the buffer dst. + * + * @remark The strings are treated as zero-terminated strings. + * @remark Guarantees that dst string will contain zero-termination. + */ void str_copy(char *dst, const char *src, int dst_size); -/* - Function: str_utf8_truncate - Truncates a utf8 encoded string to a given length. - - Parameters: - dst - Pointer to a buffer that shall receive the string. - dst_size - Size of the buffer dst. - str - String to be truncated. - truncation_len - Maximum codepoints in the returned string. - - Remarks: - - The strings are treated as utf8-encoded zero-terminated strings. - - Guarantees that dst string will contain zero-termination. -*/ +/** + * Truncates a utf8 encoded string to a given length. + * + * @ingroup Strings + * + * @param dst Pointer to a buffer that shall receive the string. + * @param dst_size Size of the buffer dst. + * @param str String to be truncated. + * @param truncation_len Maximum codepoints in the returned string. + * + * @remark The strings are treated as utf8-encoded zero-terminated strings. + * @remark Guarantees that dst string will contain zero-termination. + */ void str_utf8_truncate(char *dst, int dst_size, const char *src, int truncation_len); -/* - Function: str_truncate - Truncates a string to a given length. - - Parameters: - dst - Pointer to a buffer that shall receive the string. - dst_size - Size of the buffer dst. - src - String to be truncated. - truncation_len - Maximum length of the returned string (not - counting the zero termination). - - Remarks: - - The strings are treated as zero-terminated strings. - - Garantees that dst string will contain zero-termination. -*/ +/** + * Truncates a string to a given length. + * + * @ingroup Strings + * + * @param dst Pointer to a buffer that shall receive the string. + * @param dst_size Size of the buffer dst. + * @param src String to be truncated. + * @param truncation_len Maximum length of the returned string (not + * counting the zero termination). + * + * @remark The strings are treated as zero-terminated strings. + * @remark Garantees that dst string will contain zero-termination. + */ void str_truncate(char *dst, int dst_size, const char *src, int truncation_len); -/* - Function: str_length - Returns the length of a zero terminated string. - - Parameters: - str - Pointer to the string. - - Returns: - Length of string in bytes excluding the zero termination. +/** + * Returns the length of a zero terminated string. + * + * @ingroup Strings + * + * @param str Pointer to the string. + * + * @return Length of string in bytes excluding the zero termination. */ int str_length(const char *str); -/* - Function: str_format - Performs printf formatting into a buffer. - - Parameters: - buffer - Pointer to the buffer to receive the formatted string. - buffer_size - Size of the buffer. - format - printf formatting string. - ... - Parameters for the formatting. - - Returns: - Length of written string, even if it has been truncated - - Remarks: - - See the C manual for syntax for the printf formatting string. - - The strings are treated as zero-terminated strings. - - Guarantees that dst string will contain zero-termination. -*/ +/** + * Performs printf formatting into a buffer. + * + * @ingroup Strings + * + * @param buffer Pointer to the buffer to receive the formatted string. + * @param buffer_size Size of the buffer. + * @param format printf formatting string. + * @param ... Parameters for the formatting. + * + * @return Length of written string, even if it has been truncated + * + * @remark See the C manual for syntax for the printf formatting string. + * @remark The strings are treated as zero-terminated strings. + * @remark Guarantees that dst string will contain zero-termination. + */ int str_format(char *buffer, int buffer_size, const char *format, ...) GNUC_ATTRIBUTE((format(printf, 3, 4))); -/* - Function: str_trim_words - Trims specific number of words at the start of a string. - - Parameters: - str - String to trim the words from. - words - Count of words to trim. - - Returns: - Trimmed string - - Remarks: - - The strings are treated as zero-terminated strings. -*/ +/** + * Trims specific number of words at the start of a string. + * + * @ingroup Strings + * + * @param str String to trim the words from. + * @param words Count of words to trim. + * + * @return Trimmed string + * + * @remark The strings are treated as zero-terminated strings. + */ char *str_trim_words(char *str, int words); -/* - Function: str_sanitize_cc - Replaces all characters below 32 with whitespace. - - Parameters: - str - String to sanitize. - - Remarks: - - The strings are treated as zero-terminated strings. -*/ +/** + * Replaces all characters below 32 with whitespace. + * + * @ingroup Strings + * + * @param str String to sanitize. + * + * @remark The strings are treated as zero-terminated strings. + */ void str_sanitize_cc(char *str); -/* - Function: str_sanitize - Replaces all characters below 32 with whitespace with - exception to \t, \n and \r. - - Parameters: - str - String to sanitize. - - Remarks: - - The strings are treated as zero-terminated strings. +/** + * Replaces all characters below 32 with whitespace with + * exception to \t, \n and \r. + * + * @ingroup Strings + * + * @param str String to sanitize. + * + * @remark The strings are treated as zero-terminated strings. */ void str_sanitize(char *str); -/* - Function: str_sanitize_filename - Replaces all invalid filename characters with whitespace. - - Parameters: - str - String to sanitize. - - Remarks: - - The strings are treated as zero-terminated strings. +/** + * Replaces all invalid filename characters with whitespace. + * + * @param str String to sanitize. + * + * @remark The strings are treated as zero-terminated strings. */ void str_sanitize_filename(char *str); -/* - Function: str_clean_whitespaces - Removes leading and trailing spaces and limits the use of multiple spaces. - Parameters: - str - String to clean up - Remarks: - - The strings are treated as zero-termineted strings. -*/ +/** + * Removes leading and trailing spaces and limits the use of multiple spaces. + * + * @ingroup Strings + * + * @param str String to clean up + * + * @remark The strings are treated as zero-termineted strings. + */ void str_clean_whitespaces(char *str); -/* - Function: str_skip_to_whitespace - Skips leading non-whitespace characters(all but ' ', '\t', '\n', '\r'). - - Parameters: - str - Pointer to the string. - - Returns: - Pointer to the first whitespace character found - within the string. - - Remarks: - - The strings are treated as zero-terminated strings. -*/ +/** + * Skips leading non-whitespace characters(all but ' ', '\t', '\n', '\r'). + * + * @ingroup Strings + * + * @param str Pointer to the string. + * + * @return Pointer to the first whitespace character found + * within the string. + * + * @remark The strings are treated as zero-terminated strings. + */ char *str_skip_to_whitespace(char *str); -/* - Function: str_skip_to_whitespace_const - See str_skip_to_whitespace. -*/ +/** + * @ingroup Strings + * @see str_skip_to_whitespace + */ const char *str_skip_to_whitespace_const(const char *str); -/* - Function: str_skip_whitespaces - Skips leading whitespace characters(' ', '\t', '\n', '\r'). - - Parameters: - str - Pointer to the string. - - Returns: - Pointer to the first non-whitespace character found - within the string. - - Remarks: - - The strings are treated as zero-terminated strings. +/** + * Skips leading whitespace characters(' ', '\t', '\n', '\r'). + * + * @ingroup Strings + * + * @param str Pointer to the string. + * + * Pointer to the first non-whitespace character found + * within the string. + * + * @remark The strings are treated as zero-terminated strings. */ char *str_skip_whitespaces(char *str); -/* - Function: str_skip_whitespaces_const - See str_skip_whitespaces. -*/ +/** + * @ingroup Strings + * @see str_skip_whitespaces + */ const char *str_skip_whitespaces_const(const char *str); -/* - Function: str_comp_nocase - Compares to strings case insensitively. - - Parameters: - a - String to compare. - b - String to compare. - - Returns: - <0 - String a is less than string b - 0 - String a is equal to string b - >0 - String a is greater than string b - - Remarks: - - Only guaranteed to work with a-z/A-Z. - - The strings are treated as zero-terminated strings. -*/ +/** + * Compares to strings case insensitively. + * + * @ingroup Strings + * + * @param a String to compare. + * @param b String to compare. + * + * @return `< 0` - String a is less than string b + * @return `0` - String a is equal to string b + * @return `> 0` - String a is greater than string b + * + * @remark Only guaranteed to work with a-z/A-Z. + * @remark The strings are treated as zero-terminated strings. + */ int str_comp_nocase(const char *a, const char *b); -/* - Function: str_comp_nocase_num - Compares up to num characters of two strings case insensitively. - - Parameters: - a - String to compare. - b - String to compare. - num - Maximum characters to compare - - Returns: - <0 - String a is less than string b - 0 - String a is equal to string b - >0 - String a is greater than string b - - Remarks: - - Only guaranteed to work with a-z/A-Z. - (use str_utf8_comp_nocase_num for unicode support) - - The strings are treated as zero-terminated strings. -*/ +/** + * Compares up to num characters of two strings case insensitively. + * + * @ingroup Strings + * + * @param a String to compare. + * @param b String to compare. + * @param num Maximum characters to compare + * + * @return `< 0` - String a is less than string b + * @return `0` - String a is equal to string b + * @return `> 0` - String a is greater than string b + * + * @remark Only guaranteed to work with a-z/A-Z. + * (use str_utf8_comp_nocase_num for unicode support) + * @remark The strings are treated as zero-terminated strings. + */ int str_comp_nocase_num(const char *a, const char *b, int num); -/* - Function: str_comp - Compares two strings case sensitive. - - Parameters: - a - String to compare. - b - String to compare. - - Returns: - <0 - String a is less than string b - 0 - String a is equal to string b - >0 - String a is greater than string b - - Remarks: - - The strings are treated as zero-terminated strings. -*/ +/** + * Compares two strings case sensitive. + * + * @ingroup Strings + * + * @param a String to compare. + * @param b String to compare. + * + * @return `< 0` - String a is less than string b + * @return `0` - String a is equal to string b + * @return `> 0` - String a is greater than string b + * + * @remark The strings are treated as zero-terminated strings. + */ int str_comp(const char *a, const char *b); -/* - Function: str_comp_num - Compares up to num characters of two strings case sensitive. - - Parameters: - a - String to compare. - b - String to compare. - num - Maximum characters to compare - - Returns: - <0 - String a is less than string b - 0 - String a is equal to string b - >0 - String a is greater than string b - - Remarks: - - The strings are treated as zero-terminated strings. +/** + * Compares up to num characters of two strings case sensitive. + * + * @ingroup Strings + * + * @param a String to compare. + * @param b String to compare. + * @param num Maximum characters to compare + * + * @return `< 0` - String a is less than string b + * @return `0` - String a is equal to string b + * @return `> 0` - String a is greater than string b + * + * @remark The strings are treated as zero-terminated strings. */ int str_comp_num(const char *a, const char *b, int num); -/* - Function: str_comp_filenames - Compares two strings case sensitive, digit chars will be compared as numbers. - - Parameters: - a - String to compare. - b - String to compare. - - Returns: - <0 - String a is less than string b - 0 - String a is equal to string b - >0 - String a is greater than string b - - Remarks: - - The strings are treated as zero-terminated strings. -*/ +/** + * Compares two strings case sensitive, digit chars will be compared as numbers. + * + * @ingroup Strings + * + * @param a String to compare. + * @param b String to compare. + * + * @return `< 0` - String a is less than string b + * @return `0` - String a is equal to string b + * @return `> 0` - String a is greater than string b + * + * @remark The strings are treated as zero-terminated strings. + */ int str_comp_filenames(const char *a, const char *b); -/* - Function: str_startswith - Checks whether the string begins with a certain prefix. - - Parameter: - str - String to check. - prefix - Prefix to look for. - - Returns: - A pointer to the string str after the string prefix, or 0 if - the string prefix isn't a prefix of the string str. - - Remarks: - - The strings are treated as zero-terminated strings. -*/ +/** + * Checks whether the string begins with a certain prefix. + * + * @ingroup Strings + * + * @param str String to check. + * @param prefix Prefix to look for. + * + * @return A pointer to the string str after the string prefix, or 0 if + * the string prefix isn't a prefix of the string str. + * + * @remark The strings are treated as zero-terminated strings. + */ const char *str_startswith(const char *str, const char *prefix); -/* - Function: str_endswith - Checks whether the string ends with a certain suffix. - - Parameter: - str - String to check. - suffix - Suffix to look for. - - Returns: - A pointer to the beginning of the suffix in the string str, or - 0 if the string suffix isn't a suffix of the string str. - - Remarks: - - The strings are treated as zero-terminated strings. +/** + * Checks whether the string ends with a certain suffix. + * + * @ingroup Strings + * + * @param str String to check. + * @param suffix Suffix to look for. + * + * @return A pointer to the beginning of the suffix in the string str, or + * 0 if the string suffix isn't a suffix of the string str. + * + * @return The strings are treated as zero-terminated strings. */ const char *str_endswith(const char *str, const char *suffix); -/* - Function: str_utf8_dist - Computes the edit distance between two strings. - - Parameters: - a - First string for the edit distance. - b - Second string for the edit distance. - - Returns: - The edit distance between the both strings. - - Remarks: - - The strings are treated as zero-terminated strings. +/** + * Computes the edit distance between two strings. + * + * @param a First string for the edit distance. + * @param b Second string for the edit distance. + * + * @return The edit distance between the both strings. + * + * @remark The strings are treated as zero-terminated strings. */ int str_utf8_dist(const char *a, const char *b); -/* - Function: str_utf8_dist_buffer - Computes the edit distance between two strings, allows buffers - to be passed in. - - Parameters: - a - First string for the edit distance. - b - Second string for the edit distance. - buf - Buffer for the function. - buf_len - Length of the buffer, must be at least as long as - twice the length of both strings combined plus two. - - Returns: - The edit distance between the both strings. - - Remarks: - - The strings are treated as zero-terminated strings. +/** + * Computes the edit distance between two strings, allows buffers + * to be passed in. + * + * @ingroup Strings + * + * @param a - First string for the edit distance. + * @param b - Second string for the edit distance. + * @param buf - Buffer for the function. + * @param buf_len Length of the buffer, must be at least as long as + * twice the length of both strings combined plus two. + * + * @return The edit distance between the both strings. + * + * @remark The strings are treated as zero-terminated strings. */ int str_utf8_dist_buffer(const char *a, const char *b, int *buf, int buf_len);