(libretro-common) refinements to documentation

libretro-common/dynamic/dylib.c

@@ -75,7 +75,7 @@ static void set_dl_error(void)
  *
  * Platform independent dylib loading.
  *
- * Returns: library handle on success, otherwise NULL.
+ * @return Library handle on success, otherwise NULL.
  **/
 dylib_t dylib_load(const char *path)
 {

libretro-common/features/features_cpu.c

@@ -120,7 +120,9 @@
 #define CLOCK_REALTIME 0
 #endif
 
-/* this function is part of iOS 10 now */
+/**
+ * TODO/FIXME: clock_gettime function is part of iOS 10 now
+ **/
 static int ra_clock_gettime(int clk_ik, struct timespec *t)
 {
    struct timeval now;
@@ -153,7 +155,7 @@ static int ra_clock_gettime(int clk_ik, struct timespec *t)
  *
  * Gets performance counter.
  *
- * Returns: performance counter.
+ * @return Performance counter.
  **/
 retro_perf_tick_t cpu_features_get_perf_counter(void)
 {
@@ -221,7 +223,7 @@ retro_perf_tick_t cpu_features_get_perf_counter(void)
  *
  * Gets time in microseconds.
  *
- * Returns: time in microseconds.
+ * @return Time in microseconds.
  **/
 retro_time_t cpu_features_get_time_usec(void)
 {
@@ -383,7 +385,10 @@ static unsigned char check_arm_cpu_feature(const char* feature)
 }
 
 #if !defined(_SC_NPROCESSORS_ONLN)
-/* Parse an decimal integer starting from 'input', but not going further
+/**
+ * parse_decimal:
+ *
+ * Parse an decimal integer starting from 'input', but not going further
  * than 'limit'. Return the value into '*result'.
  *
  * NOTE: Does not skip over leading spaces, or deal with sign characters.
@@ -392,7 +397,9 @@ static unsigned char check_arm_cpu_feature(const char* feature)
  * The function returns NULL in case of error (bad format), or the new
  * position after the decimal number in case of success (which will always
  * be <= 'limit').
- */
+ *
+ * Leaf function.
+ **/
 static const char *parse_decimal(const char* input,
       const char* limit, int* result)
 {
@@ -414,7 +421,9 @@ static const char *parse_decimal(const char* input,
     return p;
 }
 
-/* Parse a textual list of cpus and store the result inside a CpuList object.
+/**
+ * cpulist_parse:
+ * Parse a textual list of cpus and store the result inside a CpuList object.
  * Input format is the following:
  * - comma-separated list of items (no spaces)
  * - each item is either a single decimal number (cpu index), or a range made
@@ -423,7 +432,7 @@ static const char *parse_decimal(const char* input,
  * Examples:   0
  *             2,4-127,128-143
  *             0-1
- */
+ **/
 static void cpulist_parse(CpuList* list, char **buf, ssize_t length)
 {
    const char* p   = (const char*)buf;
@@ -470,7 +479,11 @@ static void cpulist_parse(CpuList* list, char **buf, ssize_t length)
    }
 }
 
-/* Read a CPU list from one sysfs file */
+/**
+ * cpulist_read_from:
+ *
+ * Read a CPU list from one sysfs file
+ **/
 static void cpulist_read_from(CpuList* list, const char* filename)
 {
    ssize_t length;
@@ -495,7 +508,7 @@ static void cpulist_read_from(CpuList* list, const char* filename)
  *
  * Gets the amount of available CPU cores.
  *
- * Returns: amount of CPU cores available.
+ * @return Amount of CPU cores available.
  **/
 unsigned cpu_features_get_core_amount(void)
 {
@@ -601,7 +614,7 @@ unsigned cpu_features_get_core_amount(void)
  *
  * Gets CPU features..
  *
- * Returns: bitmask of all CPU features available.
+ * @return Bitmask of all CPU features available.
  **/
 uint64_t cpu_features_get(void)
 {

libretro-common/include/dynamic/dylib.h

@@ -49,7 +49,7 @@ typedef void (*function_t)(void);
  *
  * Platform independent dylib loading.
  *
- * Returns: library handle on success, otherwise NULL.
+ * @return Library handle on success, otherwise NULL.
  **/
 dylib_t dylib_load(const char *path);
 

libretro-common/include/features/features_cpu.h

@@ -36,7 +36,7 @@ RETRO_BEGIN_DECLS
  *
  * Gets performance counter.
  *
- * Returns: performance counter.
+ * @return Performance counter.
  **/
 retro_perf_tick_t cpu_features_get_perf_counter(void);
 
@@ -46,7 +46,7 @@ retro_perf_tick_t cpu_features_get_perf_counter(void);
  * Gets time in microseconds, from an undefined epoch.
  * The epoch may change between computers or across reboots.
  *
- * Returns: time in microseconds
+ * @return Time in microseconds
  **/
 retro_time_t cpu_features_get_time_usec(void);
 
@@ -55,7 +55,7 @@ retro_time_t cpu_features_get_time_usec(void);
  *
  * Gets CPU features.
  *
- * Returns: bitmask of all CPU features available.
+ * @return Bitmask of all CPU features available.
  **/
 uint64_t cpu_features_get(void);
 
@@ -64,7 +64,7 @@ uint64_t cpu_features_get(void);
  *
  * Gets the amount of available CPU cores.
  *
- * Returns: amount of CPU cores available.
+ * @return Amount of CPU cores available.
  **/
 unsigned cpu_features_get_core_amount(void);
 

libretro-common/include/net/net_compat.h

@@ -316,7 +316,7 @@ bool addr_6to4(struct sockaddr_storage *addr);
  *
  * Platform specific socket library initialization.
  *
- * Returns: true (1) if successful, otherwise false (0).
+ * @return true if successful, otherwise false.
  **/
 bool network_init(void);
 

libretro-common/include/net/net_http.h

@@ -36,6 +36,11 @@ struct http_connection_t;
 
 struct http_connection_t *net_http_connection_new(const char *url, const char *method, const char *data);
 
+/**
+ * net_http_connection_iterate:
+ *
+ * Leaf function.
+ **/
 bool net_http_connection_iterate(struct http_connection_t *conn);
 
 bool net_http_connection_done(struct http_connection_t *conn);
@@ -52,32 +57,73 @@ const char* net_http_connection_method(struct http_connection_t* conn);
 
 struct http_t *net_http_new(struct http_connection_t *conn);
 
-/* You can use this to call net_http_update
+/**
- * only when something will happen; select() it for reading. */
+ * net_http_fd:
+ *
+ * Leaf function.
+ *
+ * You can use this to call net_http_update
+ * only when something will happen; select() it for reading.
+ **/
 int net_http_fd(struct http_t *state);
 
-/* Returns true if it's done, or if something broke.
+/**
- * 'total' will be 0 if it's not known. */
+ * net_http_update:
+ *
+ * @return true if it's done, or if something broke.
+ * @total will be 0 if it's not known.
+ **/
 bool net_http_update(struct http_t *state, size_t* progress, size_t* total);
 
-/* 200, 404, or whatever.  */
+/**
+ * net_http_status:
+ *
+ * Report HTTP status. 200, 404, or whatever.
+ *
+ * Leaf function.
+ * 
+ * @return HTTP status code.
+ **/
 int net_http_status(struct http_t *state);
 
+/**
+ * net_http_error:
+ *
+ * Leaf function
+ **/
 bool net_http_error(struct http_t *state);
 
-/* Returns the downloaded data. The returned buffer is owned by the
+/**
- * HTTP handler; it's freed by net_http_delete.
+ * net_http_data:
  *
- * If the status is not 20x and accept_error is false, it returns NULL. */
+ * Leaf function.
+ *
+ * @return the downloaded data. The returned buffer is owned by the
+ * HTTP handler; it's freed by net_http_delete.
+ * If the status is not 20x and accept_error is false, it returns NULL.
+ **/
 uint8_t* net_http_data(struct http_t *state, size_t* len, bool accept_error);
 
-/* Cleans up all memory. */
+/**
+ * net_http_delete:
+ *
+ * Cleans up all memory.
+ **/
 void net_http_delete(struct http_t *state);
 
-/* URL Encode a string */
+/**
+ * net_http_urlencode:
+ *
+ * URL Encode a string
+ * caller is responsible for deleting the destination buffer
+ **/
 void net_http_urlencode(char **dest, const char *source);
 
-/* Re-encode a full URL */
+/**
+ * net_http_urlencode_full:
+ *
+ * Re-encode a full URL
+ **/
 void net_http_urlencode_full(char *dest, const char *source, size_t size);
 
 RETRO_END_DECLS

libretro-common/include/net/net_http_parse.h

@@ -43,7 +43,7 @@ RETRO_BEGIN_DECLS
  * The buffer pointed to by @link is filled with the URL path the link points to,
  * and @name is filled with the title portion of the link.
  *
- * Returns: 0 if URL was parsed completely, otherwise 1.
+ * @return 0 if URL was parsed completely, otherwise 1.
  **/
 int string_parse_html_anchor(const char *line, char *link, char *name,
       size_t link_size, size_t name_size);

libretro-common/include/playlists/label_sanitization.h

@@ -22,6 +22,11 @@
 #include <stddef.h>
 #include <boolean.h>
 
+/**
+ * label_sanitize:
+ *
+ * NOTE: Does not work with nested blocks.
+ **/
 void label_sanitize(char *label, bool (*left)(char*), bool (*right)(char*));
 
 void label_remove_parens(char *label);

libretro-common/include/streams/file_stream.h

@@ -59,7 +59,7 @@ int64_t filestream_truncate(RFILE *stream, int64_t length);
  * @bufsize            : optional buffer size (-1 or 0 to use default)
  *
  * Opens a file for reading or writing, depending on the requested mode.
- * Returns a pointer to an RFILE if opened successfully, otherwise NULL.
+ * @return A pointer to an RFILE if opened successfully, otherwise NULL.
  **/
 RFILE* filestream_open(const char *path, unsigned mode, unsigned hints);
 
@@ -75,6 +75,17 @@ void filestream_rewind(RFILE *stream);
 
 int filestream_close(RFILE *stream);
 
+/**
+ * filestream_read_file:
+ * @path             : path to file.
+ * @buf              : buffer to allocate and read the contents of the
+ *                     file into. Needs to be freed manually.
+ * @len              : optional output integer containing bytes read.
+ *
+ * Read the contents of a file into @buf.
+ *
+ * @return Non-zero on success.
+ */
 int64_t filestream_read_file(const char *path, void **buf, int64_t *len);
 
 char* filestream_gets(RFILE *stream, char *s, size_t len);
@@ -87,6 +98,16 @@ int filestream_scanf(RFILE *stream, const char* format, ...);
 
 int filestream_eof(RFILE *stream);
 
+/**
+ * filestream_write_file:
+ * @path             : path to file.
+ * @data             : contents to write to the file.
+ * @size             : size of the contents.
+ *
+ * Writes data to a file.
+ *
+ * @return true on success, otherwise false.
+ **/
 bool filestream_write_file(const char *path, const void *data, int64_t size);
 
 int filestream_putc(RFILE *stream, int c);
@@ -107,7 +128,11 @@ const char* filestream_get_path(RFILE *stream);
 
 bool filestream_exists(const char *path);
 
-/* Returned pointer must be freed by the caller. */
+/**
+ * filestream_getline:
+ *
+ * Returned pointer must be freed by the caller.
+ **/
 char* filestream_getline(RFILE *stream);
 
 libretro_vfs_implementation_file* filestream_get_vfs_handle(RFILE *stream);

libretro-common/include/string/stdstring.h

@@ -185,6 +185,14 @@ char *string_trim_whitespace(char *const s);
 
 /**
  * word_wrap:
+ * @dst                : pointer to destination buffer.
+ * @dst_size           : size of destination buffer.
+ * @src                : pointer to input string.
+ * @line_width         : max number of characters per line.
+ * @wideglyph_width    : not used, but is necessary to keep
+ *                       compatibility with word_wrap_wideglyph().
+ * @max_lines          : max lines of destination string.
+ *                       0 means no limit.
  *
  * Wraps string specified by 'src' to destination buffer
  * specified by 'dst' and 'dst_size'.
@@ -193,52 +201,42 @@ char *string_trim_whitespace(char *const s);
  * regular Latin characters - i.e. it will not wrap
  * correctly any text containing so-called 'wide' Unicode
  * characters (e.g. CJK languages, emojis, etc.).
- *
- * @param dst             pointer to destination buffer.
- * @param dst_size        size of destination buffer.
- * @param src             pointer to input string.
- * @param line_width      max number of characters per line.
- * @param wideglyph_width not used, but is necessary to keep
- *                        compatibility with word_wrap_wideglyph().
- * @param max_lines       max lines of destination string.
- *                        0 means no limit.
  **/
 void word_wrap(char *dst, size_t dst_size, const char *src,
       int line_width, int wideglyph_width, unsigned max_lines);
 
 /**
  * word_wrap_wideglyph:
+ * @dst                : pointer to destination buffer.
+ * @dst_size           : size of destination buffer.
+ * @src                : pointer to input string.
+ * @line_width         : max number of characters per line.
+ * @wideglyph_width    : effective width of 'wide' Unicode glyphs.
+ *                       the value here is normalised relative to the
+ *                       typical on-screen pixel width of a regular
+ *                       Latin character:
+ *                       - a regular Latin character is defined to
+ *                         have an effective width of 100
+ *                       - wideglyph_width = 100 * (wide_character_pixel_width / latin_character_pixel_width)
+ *                       - e.g. if 'wide' Unicode characters in 'src'
+ *                         have an on-screen pixel width twice that of
+ *                         regular Latin characters, wideglyph_width
+ *                         would be 200
+ * @max_lines          : max lines of destination string.
+ *                       0 means no limit.
  *
- * Wraps string specified by 'src' to destination buffer
+ * Wraps string specified by @src to destination buffer
- * specified by 'dst' and 'dst_size'.
+ * specified by @dst and @dst_size.
  * This function assumes that all glyphs in the string
  * are:
  * - EITHER 'non-wide' Unicode glyphs, with an on-screen
  *   pixel width similar to that of regular Latin characters
  * - OR 'wide' Unicode glyphs (e.g. CJK languages, emojis, etc.)
- *   with an on-screen pixel width defined by 'wideglyph_width'
+ *   with an on-screen pixel width defined by @wideglyph_width
  * Note that wrapping may occur in inappropriate locations
- * if 'src' string contains 'wide' Unicode characters whose
+ * if @src string contains 'wide' Unicode characters whose
  * on-screen pixel width deviates greatly from the set
- * 'wideglyph_width' value.
+ * @wideglyph_width value.
- *
- * @param dst             pointer to destination buffer.
- * @param dst_size        size of destination buffer.
- * @param src             pointer to input string.
- * @param line_width      max number of characters per line.
- * @param wideglyph_width effective width of 'wide' Unicode glyphs.
- *                        the value here is normalised relative to the
- *                        typical on-screen pixel width of a regular
- *                        Latin character:
- *                        - a regular Latin character is defined to
- *                          have an effective width of 100
- *                        - wideglyph_width = 100 * (wide_character_pixel_width / latin_character_pixel_width)
- *                        - e.g. if 'wide' Unicode characters in 'src'
- *                          have an on-screen pixel width twice that of
- *                          regular Latin characters, wideglyph_width
- *                          would be 200
- * @param max_lines       max lines of destination string.
- *                        0 means no limit.
  **/
 void word_wrap_wideglyph(char *dst, size_t dst_size, const char *src,
       int line_width, int wideglyph_width, unsigned max_lines);

libretro-common/net/net_compat.c

@@ -269,7 +269,7 @@ static char netmask[16] = {0};
  *
  * Platform specific socket library initialization.
  *
- * Returns: true (1) if successful, otherwise false (0).
+ * @return true if successful, otherwise false.
  **/
 bool network_init(void)
 {
@@ -483,7 +483,11 @@ struct in_addr6_compat
 /* Taken from https://github.com/skywind3000/easenet/blob/master/inetbase.c
  */
 
-/* convert presentation format to network format */
+/**
+ * inet_ntop4x:
+ *
+ * Convert presentation format to network format.
+ **/
 static const char *
 inet_ntop4x(const unsigned char *src, char *dst, size_t size)
 {
@@ -503,7 +507,11 @@ error:
    return NULL;
 }
 
-/* convert presentation format to network format */
+/**
+ * inet_ntop6x:
+ *
+ * Convert presentation format to network format.
+ **/
 static const char *
 inet_ntop6x(const unsigned char *src, char *dst, size_t size)
 {
@@ -593,8 +601,12 @@ error:
    return NULL;
 }
 
-/* convert network format to presentation format */
+/* 
-/* another inet_ntop, supports AF_INET/AF_INET6 */
+ * isockaddr_ntop:
+ *
+ * Convert network format to presentation format.
+ * Another inet_ntop, supports AF_INET/AF_INET6
+ **/
 static const char *isockaddr_ntop(int af,
       const void *src, char *dst, size_t size)
 {

libretro-common/net/net_http.c

@@ -88,8 +88,12 @@ struct http_connection_t
    int port;
 };
 
-/* URL Encode a string
+/**
-   caller is responsible for deleting the destination buffer */
+ * net_http_urlencode:
+ *
+ * URL Encode a string
+ * caller is responsible for deleting the destination buffer
+ **/
 void net_http_urlencode(char **dest, const char *source)
 {
    static const char urlencode_lut[256] = 
@@ -377,7 +381,11 @@ void net_http_urlencode(char **dest, const char *source)
    (*dest)[len - 1] = '\0';
 }
 
-/* Re-encode a full URL */
+/**
+ * net_http_urlencode_full:
+ *
+ * Re-encode a full URL
+ **/
 void net_http_urlencode_full(char *dest,
       const char *source, size_t size)
 {
@@ -547,6 +555,11 @@ error:
    return NULL;
 }
 
+/**
+ * net_http_connection_iterate:
+ *
+ * Leaf function.
+ **/
 bool net_http_connection_iterate(struct http_connection_t *conn)
 {
    if (!conn)
@@ -864,6 +877,14 @@ error:
    return NULL;
 }
 
+/**
+ * net_http_fd:
+ *
+ * Leaf function.
+ *
+ * You can use this to call net_http_update
+ * only when something will happen; select() it for reading.
+ **/
 int net_http_fd(struct http_t *state)
 {
    if (!state)
@@ -871,6 +892,12 @@ int net_http_fd(struct http_t *state)
    return state->sock_state.fd;
 }
 
+/**
+ * net_http_update:
+ *
+ * @return true if it's done, or if something broke.
+ * @total will be 0 if it's not known.
+ **/
 bool net_http_update(struct http_t *state, size_t* progress, size_t* total)
 {
    ssize_t newlen = 0;
@@ -1117,6 +1144,15 @@ parse_again:
    return (state->part == P_DONE);
 }
 
+/**
+ * net_http_status:
+ *
+ * Report HTTP status. 200, 404, or whatever.
+ *
+ * Leaf function.
+ * 
+ * @return HTTP status code.
+ **/
 int net_http_status(struct http_t *state)
 {
    if (!state)
@@ -1124,12 +1160,21 @@ int net_http_status(struct http_t *state)
    return state->status;
 }
 
+/**
+ * net_http_data:
+ *
+ * Leaf function.
+ *
+ * @return the downloaded data. The returned buffer is owned by the
+ * HTTP handler; it's freed by net_http_delete().
+ * If the status is not 20x and accept_error is false, it returns NULL.
+ **/
 uint8_t* net_http_data(struct http_t *state, size_t* len, bool accept_error)
 {
    if (!state)
       return NULL;
 
-   if (!accept_error && net_http_error(state))
+   if (!accept_error && (state->error || state->status < 200 || state->status > 299))
    {
       if (len)
          *len = 0;
@@ -1142,6 +1187,11 @@ uint8_t* net_http_data(struct http_t *state, size_t* len, bool accept_error)
    return (uint8_t*)state->data;
 }
 
+/**
+ * net_http_delete:
+ *
+ * Cleans up all memory.
+ **/
 void net_http_delete(struct http_t *state)
 {
    if (!state)
@@ -1161,7 +1211,12 @@ void net_http_delete(struct http_t *state)
    free(state);
 }
 
+/**
+ * net_http_error:
+ *
+ * Leaf function
+ **/
 bool net_http_error(struct http_t *state)
 {
-   return (state->error || state->status<200 || state->status>299);
+   return (state->error || state->status < 200 || state->status > 299);
 }

libretro-common/net/net_http_parse.c

@@ -35,7 +35,7 @@
  * The buffer pointed to by @link is filled with the URL path the link points to,
  * and @name is filled with the title portion of the link.
  *
- * Returns: 0 if URL was parsed completely, otherwise 1.
+ * @return 0 if URL was parsed completely, otherwise 1.
  **/
 int string_parse_html_anchor(const char *line, char *link, char *name,
       size_t link_size, size_t name_size)

libretro-common/playlists/label_sanitization.c

@@ -61,9 +61,11 @@ const char *region_strings[REGION_STRINGS_LENGTH] = {
    "(USA, Europe)"
 };
 
-/*
+/**
- * Does not work with nested blocks.
+ * label_sanitize:
- */
+ *
+ * NOTE: Does not work with nested blocks.
+ **/
 void label_sanitize(char *label, bool (*left)(char*), bool (*right)(char*))
 {
    bool copy = true;

libretro-common/streams/file_stream.c

@@ -161,7 +161,7 @@ int64_t filestream_truncate(RFILE *stream, int64_t length)
  * @hints              :
  *
  * Opens a file for reading or writing, depending on the requested mode.
- * Returns a pointer to an RFILE if opened successfully, otherwise NULL.
+ * @return A pointer to an RFILE if opened successfully, otherwise NULL.
  **/
 RFILE* filestream_open(const char *path, unsigned mode, unsigned hints)
 {
@@ -539,7 +539,7 @@ int filestream_close(RFILE *stream)
  *
  * Read the contents of a file into @buf.
  *
- * Returns: non zero on success.
+ * @return Non-zero on success.
  */
 int64_t filestream_read_file(const char *path, void **buf, int64_t *len)
 {
@@ -556,9 +556,7 @@ int64_t filestream_read_file(const char *path, void **buf, int64_t *len)
       return 0;
    }
 
-   content_buf_size = filestream_get_size(file);
+   if ((content_buf_size = filestream_get_size(file)) < 0)
-
-   if (content_buf_size < 0)
       goto error;
 
    if (!(content_buf = malloc((size_t)(content_buf_size + 1))))
@@ -603,8 +601,8 @@ error:
  *
  * Writes data to a file.
  *
- * Returns: true (1) on success, false (0) otherwise.
+ * @return true on success, otherwise false.
- */
+ **/
 bool filestream_write_file(const char *path, const void *data, int64_t size)
 {
    int64_t ret   = 0;
@@ -619,8 +617,12 @@ bool filestream_write_file(const char *path, const void *data, int64_t size)
    return (ret == size);
 }
 
-/* Returned pointer must be freed by the caller. */
+/**
-char* filestream_getline(RFILE *stream)
+ * filestream_getline:
+ *
+ * Returned pointer must be freed by the caller.
+ **/
+char *filestream_getline(RFILE *stream)
 {
    char *newline_tmp  = NULL;
    size_t cur_size    = 8;
@@ -635,7 +637,7 @@ char* filestream_getline(RFILE *stream)
       return NULL;
    }
 
-   in                 = filestream_getc(stream);
+   in = filestream_getc(stream);
 
    while (in != EOF && in != '\n')
    {

libretro-common/string/stdstring.c

@@ -200,6 +200,14 @@ char *string_trim_whitespace(char *const s)
 
 /**
  * word_wrap:
+ * @dst                : pointer to destination buffer.
+ * @dst_size           : size of destination buffer.
+ * @src                : pointer to input string.
+ * @line_width         : max number of characters per line.
+ * @wideglyph_width    : not used, but is necessary to keep
+ *                       compatibility with word_wrap_wideglyph().
+ * @max_lines          : max lines of destination string.
+ *                       0 means no limit.
  *
  * Wraps string specified by 'src' to destination buffer
  * specified by 'dst' and 'dst_size'.
@@ -208,15 +216,6 @@ char *string_trim_whitespace(char *const s)
  * regular Latin characters - i.e. it will not wrap
  * correctly any text containing so-called 'wide' Unicode
  * characters (e.g. CJK languages, emojis, etc.).
- *
- * @param dst             pointer to destination buffer.
- * @param dst_size        size of destination buffer.
- * @param src             pointer to input string.
- * @param line_width      max number of characters per line.
- * @param wideglyph_width not used, but is necessary to keep
- *                        compatibility with word_wrap_wideglyph().
- * @param max_lines       max lines of destination string.
- *                        0 means no limit.
  **/
 void word_wrap(char *dst, size_t dst_size, const char *src,
       int line_width, int wideglyph_width, unsigned max_lines)
@@ -296,37 +295,36 @@ void word_wrap(char *dst, size_t dst_size, const char *src,
 
 /**
  * word_wrap_wideglyph:
+ * @dst                : pointer to destination buffer.
+ * @dst_size           : size of destination buffer.
+ * @src                : pointer to input string.
+ * @line_width         : max number of characters per line.
+ * @wideglyph_width    : effective width of 'wide' Unicode glyphs.
+ *                       the value here is normalised relative to the
+ *                       typical on-screen pixel width of a regular
+ *                       Latin character:
+ *                       - a regular Latin character is defined to
+ *                         have an effective width of 100
+ *                       - wideglyph_width = 100 * (wide_character_pixel_width / latin_character_pixel_width)
+ *                       - e.g. if 'wide' Unicode characters in 'src'
+ *                         have an on-screen pixel width twice that of
+ *                         regular Latin characters, wideglyph_width
+ *                         would be 200
+ * @max_lines          : max lines of destination string.
+ *                       0 means no limit.
  *
- * Wraps string specified by 'src' to destination buffer
+ * Wraps string specified by @src to destination buffer
- * specified by 'dst' and 'dst_size'.
+ * specified by @dst and @dst_size.
  * This function assumes that all glyphs in the string
  * are:
  * - EITHER 'non-wide' Unicode glyphs, with an on-screen
  *   pixel width similar to that of regular Latin characters
  * - OR 'wide' Unicode glyphs (e.g. CJK languages, emojis, etc.)
- *   with an on-screen pixel width defined by 'wideglyph_width'
+ *   with an on-screen pixel width defined by @wideglyph_width
  * Note that wrapping may occur in inappropriate locations
- * if 'src' string contains 'wide' Unicode characters whose
+ * if @src string contains 'wide' Unicode characters whose
  * on-screen pixel width deviates greatly from the set
- * 'wideglyph_width' value.
+ * @wideglyph_width value.
- *
- * @param dst             pointer to destination buffer.
- * @param dst_size        size of destination buffer.
- * @param src             pointer to input string.
- * @param line_width      max number of characters per line.
- * @param wideglyph_width effective width of 'wide' Unicode glyphs.
- *                        the value here is normalised relative to the
- *                        typical on-screen pixel width of a regular
- *                        Latin character:
- *                        - a regular Latin character is defined to
- *                          have an effective width of 100
- *                        - wideglyph_width = 100 * (wide_character_pixel_width / latin_character_pixel_width)
- *                        - e.g. if 'wide' Unicode characters in 'src'
- *                          have an on-screen pixel width twice that of
- *                          regular Latin characters, wideglyph_width
- *                          would be 200
- * @param max_lines       max lines of destination string.
- *                        0 means no limit.
  **/
 void word_wrap_wideglyph(char *dst, size_t dst_size,
       const char *src, int line_width,