Fix of DOXYGEN docs: @return instead of @returns

...and other minor corrections. Signed-off-by: Andrew Borodin <aborodin@vmail.ru>
2012-11-05 17:57:50 +04:00 · 2012-11-05 17:57:50 +04:00 · 2940b7455d
--- a/lib/charsets.c
+++ b/lib/charsets.c
@ -260,7 +260,7 @@ get_codepage_index (const char *id)
 /* --------------------------------------------------------------------------------------------- */
 /** Check if specified encoding can be used in mc.
 * @param encoding name of encoding
- * @returns TRUE if encoding has supported by mc, FALSE otherwise
+ * @return TRUE if encoding is supported by mc, FALSE otherwise
 */

 gboolean
--- a/lib/lock.c
+++ b/lib/lock.c
@ -266,7 +266,7 @@ lock_file (const vfs_path_t * fname_vpath)
 /* --------------------------------------------------------------------------------------------- */
 /**
 * Lowers file lock if possible
- * @returns  Always 0
+ * @return  Always 0
 */

 int
--- a/lib/strutil.h
+++ b/lib/strutil.h
@ -533,7 +533,7 @@ void str_msg_term_size (const char *text, int *lines, int *columns);
 * @param needle pointer to string
 * @param skip_count skip first bytes
 *
- * @returns pointer to skip_count+1 needle (or NULL if not found).
+ * @return pointer to skip_count+1 needle (or NULL if not found).
 */

 char *strrstr_skip_count (const char *haystack, const char *needle, size_t skip_count);
@ -564,7 +564,7 @@ str_replace (char *s, char from, char to)
 * @param dest pointer to string
 * @param src pointer to string
 *
- * @returns a newly allocated string
+ * @return newly allocated string
 *
 */

--- a/lib/strutil/strescape.c
+++ b/lib/strutil/strescape.c
@ -166,7 +166,7 @@ strutils_unescape (const char *src, gsize src_len, const char *unescaped_chars,
 *
 * @param src string for escaping
 *
- * @returns escaped string (which needs to be freed later) or NULL when NULL string is passed.
+ * @return escaped string (which needs to be freed later) or NULL when NULL string is passed.
 */

 char *
@ -199,7 +199,7 @@ strutils_regex_escape (const char *src)
 *
 * @param text string for unescaping
 *
- * @returns unescaped string (which needs to be freed)
+ * @return unescaped string (which needs to be freed)
 */

 char *
@ -231,7 +231,7 @@ strutils_regex_unescape (const char *text)
 * @param start string for checking
 * @param current pointer to checked character
 *
- * @returns TRUE if string contain escaped chars otherwise return FALSE
+ * @return TRUE if string contain escaped chars otherwise return FALSE
 */

 gboolean
--- a/lib/util.c
+++ b/lib/util.c
@ -918,7 +918,7 @@ wipe_password (char *passwd)
 *
 * @param p pointer to string
 *
- * @returns a newly allocated string
+ * @return newly allocated string
 */

 char *
--- a/lib/utilunix.c
+++ b/lib/utilunix.c
@ -286,7 +286,7 @@ my_system (int flags, const char *shell, const char *command)
 *
 * @param directory pointer to the path
 *
- * @returns a newly allocated string, even if it's unchanged.
+ * @return newly allocated string, even if it's unchanged.
 */

 char *
@ -385,7 +385,7 @@ open_error_pipe (void)
 * @param error '-1' - ignore errors, '0' - display warning, '1' - display error
 * @param text is prepended to the error message from the pipe
 *
- * @returns not 0 if an error was displayed
+ * @return not 0 if an error was displayed
 */

 int
--- a/lib/vfs/path.c
+++ b/lib/vfs/path.c
@ -1058,7 +1058,7 @@ vfs_path_element_need_cleanup_converter (const vfs_path_element_t * element)
 * @param vpath data for serialization
 * @param error contain pointer to object for handle error code and message
 *
- * @returns serialized vpath as newly allocated string
+ * @return serialized vpath as newly allocated string
 */

 char *
@ -1452,7 +1452,7 @@ vfs_path_vtokens_get (const vfs_path_t * vpath, ssize_t start_position, ssize_t
 * @param element path element
 * @param keep_password TRUE or FALSE
 *
- * @returns newly allocated string
+ * @return newly allocated string
 */

 char *
--- a/lib/vfs/vfs.c
+++ b/lib/vfs/vfs.c
@ -626,7 +626,7 @@ vfs_change_encoding (vfs_path_t * vpath, const char *encoding)
 * @param src_fsize source file size
 * @param dest_fsize destination file size (if destination exists, otherwise should be 0)
 *
- * @returns 0 if success and non-zero otherwise.
+ * @return 0 if success and non-zero otherwise.
 * Note: function doesn't touch errno global variable.
 */

--- a/lib/widget/input.c
+++ b/lib/widget/input.c
@ -984,7 +984,7 @@ input_event (Gpm_Event * event, void *data)
  * @param def_text             Default text filled in widget
  * @param histname             Name of history
  * @param completion_flags     Flags for specify type of completions
-  * @returns                    WInput object
+  * @return                     WInput object
  */
 WInput *
 input_new (int y, int x, const int *input_colors, int width, const char *def_text,
@ -1104,7 +1104,7 @@ input_callback (Widget * w, widget_msg_t msg, int parm)
 /* --------------------------------------------------------------------------------------------- */

 /** Get default colors for WInput widget.
-  * @returns default colors
+  * @return default colors
  */
 const int *
 input_get_default_colors (void)
--- a/src/diffviewer/ydiff.c
+++ b/src/diffviewer/ydiff.c
@ -159,7 +159,7 @@ rewrite_backup_content (const vfs_path_t * from_file_name_vpath, const char *to_
 * @note the name is not altered if this function fails
 *
 * @param[out] name address of a pointer to store the temporary name
- * @returns file descriptor on success, negative on error
+ * @return file descriptor on success, negative on error
 */

 static int
@ -186,7 +186,7 @@ open_temp (void **name)
 * Alocate file structure and associate file descriptor to it.
 *
 * @param fd file descriptor
- * @returns file structure
+ * @return file structure
 */

 static FBUF *
@ -222,7 +222,7 @@ f_dopen (int fd)
 * Free file structure without closing the file.
 *
 * @param fs file structure
- * @returns 0 on success, non-zero on error
+ * @return 0 on success, non-zero on error
 */

 static int
@ -246,8 +246,7 @@ f_free (FBUF * fs)
 * Open a binary temporary file in R/W mode.
 * @note the file will be deleted when closed
 *
- * @returns file structure
- *
+ * @return file structure
 */
 static FBUF *
 f_temp (void)
@ -279,7 +278,7 @@ f_temp (void)
 * @param filename file name
 * @param flags open mode, a combination of O_RDONLY, O_WRONLY, O_RDWR
 *
- * @returns file structure
+ * @return file structure
 */

 static FBUF *
@ -314,8 +313,7 @@ f_open (const char *filename, int flags)
 * @param size size of buffer
 * @param fs file structure
 *
- * @returns number of bytes read
- *
+ * @return number of bytes read
 */

 static size_t
@ -357,8 +355,7 @@ f_gets (char *buf, size_t size, FBUF * fs)
 * @param off offset
 * @param whence seek directive: SEEK_SET, SEEK_CUR or SEEK_END
 *
- * @returns position in file, starting from begginning
- *
+ * @return position in file, starting from begginning
 */

 static off_t
@ -397,7 +394,7 @@ f_seek (FBUF * fs, off_t off, int whence)
 *
 * @param fs file structure
 *
- * @returns 0 if success, non-zero on error
+ * @return 0 if success, non-zero on error
 */

 static off_t
@ -421,8 +418,7 @@ f_reset (FBUF * fs)
 * @param buf source buffer
 * @param size size of buffer
 *
- * @returns number of written bytes, -1 on error
- *
+ * @return number of written bytes, -1 on error
 */

 static ssize_t
@ -444,8 +440,7 @@ f_write (FBUF * fs, const char *buf, size_t size)
 *
 * @param fs file structure
 *
- * @returns current file size on success, negative on error
- *
+ * @return current file size on success, negative on error
 */

 static off_t
@ -474,8 +469,7 @@ f_trunc (FBUF * fs)
 * @note if this is temporary file, it is deleted
 *
 * @param fs file structure
- * @returns 0 on success, non-zero on error
- *
+ * @return 0 on success, non-zero on error
 */

 static int
@ -500,7 +494,7 @@ f_close (FBUF * fs)
 * @param cmd shell command line
 * @param flags open mode, either O_RDONLY or O_WRONLY
 *
- * @returns file structure
+ * @return file structure
 */

 static FBUF *
@ -540,7 +534,7 @@ p_open (const char *cmd, int flags)
 * Close pipe stream.
 *
 * @param fs structure
- * @returns 0 on success, non-zero on error
+ * @return 0 on success, non-zero on error
 */

 static int
@ -563,7 +557,7 @@ p_close (FBUF * fs)
 * Get one char (byte) from string
 *
 * @param char * str, gboolean * result
- * @returns int as character or 0 and result == FALSE if fail
+ * @return int as character or 0 and result == FALSE if fail
 */

 static int
@ -584,8 +578,7 @@ dview_get_byte (char *str, gboolean * result)
 * Get utf multibyte char from string
 *
 * @param char * str, int * char_width, gboolean * result
- * @returns int as utf character or 0 and result == FALSE if fail
- *
+ * @return int as utf character or 0 and result == FALSE if fail
 */

 static int
@ -666,7 +659,7 @@ dview_str_utf8_offset_to_pos (const char *text, size_t length)
 *
 * @param[in,out] str string to parse
 * @param[out] n extracted number
- * @returns 0 if success, otherwise non-zero
+ * @return 0 if success, otherwise non-zero
 */

 static int
@ -690,7 +683,7 @@ scan_deci (const char **str, int *n)
 *
 * @param p string to parse
 * @param ops list of diff statements
- * @returns 0 if success, otherwise non-zero
+ * @return 0 if success, otherwise non-zero
 */

 static int
@ -766,7 +759,7 @@ scan_line (const char *p, GArray * ops)
 *
 * @param f stream to read from
 * @param ops list of diff statements to fill
- * @returns positive number indicating number of hunks, otherwise negative
+ * @return positive number indicating number of hunks, otherwise negative
 */

 static int
@ -807,7 +800,7 @@ scan_diff (FBUF * f, GArray * ops)
 * @param file2 second file to compare
 * @param ops list of diff statements to fill
 *
- * @returns positive number indicating number of hunks, otherwise negative
+ * @return positive number indicating number of hunks, otherwise negative
 */

 static int
@ -862,7 +855,7 @@ dff_execute (const char *args, const char *extra, const char *file1, const char
 * @param printer printf-like function to be used for displaying
 * @param ctx printer context
 *
- * @returns 0 if success, otherwise non-zero
+ * @return 0 if success, otherwise non-zero
 */

 static int
@ -1039,7 +1032,7 @@ dff_reparse (diff_place_t ord, const char *filename, const GArray * ops, DFUNC p
 * @param ret list of offsets for longest common substrings inside each string
 * @param min minimum length of common substrings
 *
- * @returns 0 if success, nonzero otherwise
+ * @return 0 if success, nonzero otherwise
 */

 static int
@ -1136,7 +1129,7 @@ lcsubstr (const char *s, int m, const char *t, int n, GArray * ret, int min)
 * @param hdiff list of horizontal diff ranges to fill
 * @param depth recursion depth
 *
- * @returns 0 if success, nonzero otherwise
+ * @return 0 if success, nonzero otherwise
 */

 static gboolean
@ -1216,7 +1209,7 @@ hdiff_multi (const char *s, const char *t, const BRACKET bracket, int min, GArra
 * @param hdiff list of horizontal diff ranges to fill
 * @param depth recursion depth
 *
- * @returns 0 if success, nonzero otherwise
+ * @return 0 if success, nonzero otherwise
 */

 static gboolean
@ -1251,7 +1244,7 @@ hdiff_scan (const char *s, int m, const char *t, int n, int min, GArray * hdiff,
 * @param hdiff horizontal diff structure
 * @param ord DIFF_LEFT if reading from first file, DIFF_RIGHT if reading from 2nd file
 *
- * @returns TRUE if inside hdiff limits, FALSE otherwise
+ * @return TRUE if inside hdiff limits, FALSE otherwise
 */

 static gboolean
@ -1285,7 +1278,7 @@ is_inside (int k, GArray * hdiff, diff_place_t ord)
 * @param base virtual base of this string, needed to calculate tabs
 * @param ts tab size
 *
- * @returns new virtual base
+ * @return new virtual base
 */

 static int
@ -1322,7 +1315,7 @@ cvt_cpy (char *dst, const char *src, size_t srcsize, int base, int ts)
 * @param base virtual base of this string, needed to calculate tabs
 * @param ts tab size
 *
- * @returns new virtual base
+ * @return new virtual base
 *
 * @note The procedure returns when all bytes are consumed from 'src'
 *       or 'dstsize' bytes are written to 'dst'
@ -1368,7 +1361,7 @@ cvt_ncpy (char *dst, int dstsize, const char **_src, size_t srcsize, int base, i
 * @param ts tab size
 * @param show_cr show trailing carriage return as ^M
 *
- * @returns negative on error, otherwise number of bytes except padding
+ * @return negative on error, otherwise number of bytes except padding
 */

 static int
@ -1465,7 +1458,7 @@ cvt_mget (const char *src, size_t srcsize, char *dst, int dstsize, int skip, int
 * @param ord DIFF_LEFT if reading from first file, DIFF_RIGHT if reading from 2nd file
 * @param att buffer of attributes
 *
- * @returns negative on error, otherwise number of bytes except padding
+ * @return negative on error, otherwise number of bytes except padding
 */

 static int
@ -1566,7 +1559,7 @@ cvt_mgeta (const char *src, size_t srcsize, char *dst, int dstsize, int skip, in
 * @param ts tab size
 * @param show_cr show trailing carriage return as ^M
 *
- * @returns negative on error, otherwise number of bytes except padding
+ * @return negative on error, otherwise number of bytes except padding
 */

 static int
@ -1976,7 +1969,7 @@ find_next_hunk (const GArray * a, size_t pos)
 * Find start and end lines of the current hunk.
 *
 * @param dview WDiff widget
- * @returns boolean and
+ * @return boolean and
 * start_line1 first line of current hunk (file[0])
 * end_line1 last line of current hunk (file[0])
 * start_line1 first line of current hunk (file[0])
--- a/src/editor/bookmark.c
+++ b/src/editor/bookmark.c
@ -145,7 +145,7 @@ book_mark_find (WEdit * edit, long line)
 * @param edit editor object
 * @param line line where book mark is
 * @param c color of book mark
- * @returns TRUE if bookmark exists at this line of color c, FALSE otherwise
+ * @return TRUE if bookmark exists at this line of color c, FALSE otherwise
 */

 gboolean
@ -209,7 +209,7 @@ book_mark_insert (WEdit * edit, long line, int c)
 * @param edit editor object
 * @param line line where book mark is
 * @param c color of book mark or -1 to clear all book marks on this line
- * @returns FALSE if not found, TRUE otherwise
+ * @return FALSE if not found, TRUE otherwise
 */

 gboolean
--- a/src/editor/edit-impl.h
+++ b/src/editor/edit-impl.h
@ -336,7 +336,7 @@ void edit_execute_cmd (WEdit * edit, unsigned long command, int char_for_inserti
 * To do it, allocate a new widget, initialize it and, if the new file
 * was loaded, copy the data to the old widget.
 *
- * @returns TRUE on success, FALSE on failure.
+ * @return TRUE on success, FALSE on failure.
 */
 static inline gboolean
 edit_reload (WEdit * edit, const vfs_path_t * filename_vpath)
--- a/src/editor/edit.c
+++ b/src/editor/edit.c
@ -194,7 +194,7 @@ edit_init_buffers (WEdit * edit)
 /**
 * Load file OR text into buffers.  Set cursor to the beginning of file.
 *
- * @returns FALSE on error.
+ * @return FALSE on error.
 */

 static gboolean
@ -326,7 +326,7 @@ edit_insert_stream (WEdit * edit, FILE * f)
  * @param edit           editor object
  * @param filename_vpath file name
  * @param st             buffer for store stat info
-  * @returns TRUE for success, FALSE for error.
+  * @return TRUE for success, FALSE for error.
  */

 static gboolean
@ -1740,7 +1740,7 @@ edit_move_block_to_left (WEdit * edit)
 /* --------------------------------------------------------------------------------------------- */
 /**
 * prints at the cursor
- * @returns the number of chars printed
+ * @return number of chars printed
 */

 static size_t
@ -1918,7 +1918,7 @@ edit_get_write_filter (const vfs_path_t * write_name_vpath, const vfs_path_t * f
 /**
 * @param edit   editor object
 * @param f      value of stream file
- * @returns      the length of the file
+ * @return       the length of the file
 */

 off_t
@ -2347,7 +2347,7 @@ edit_clean (WEdit * edit)
 * To do it, allocate a new widget, initialize it and, if the new file
 * was loaded, copy the data to the old widget.
 *
- * @returns TRUE on success, FALSE on failure.
+ * @return TRUE on success, FALSE on failure.
 */
 gboolean
 edit_reload_line (WEdit * edit, const vfs_path_t * filename_vpath, long line)
--- a/src/editor/editcmd.c
+++ b/src/editor/editcmd.c
@ -2055,7 +2055,7 @@ edit_save_confirm_cmd (WEdit * edit)
 /**
  * Ask file to edit and load it.
  *
-  * @returns TRUE on success or cancel of ask.
+  * @return TRUE on success or cancel of ask.
  */

 gboolean
@ -2085,7 +2085,7 @@ edit_load_cmd (Dlg_head * h)
 /**
  * Load syntax file to edit.
  *
-  * @returns TRUE on success
+  * @return TRUE on success
  */

 gboolean
@ -2130,7 +2130,7 @@ edit_load_syntax_file (Dlg_head * h)
 /**
  * Load menu file to edit.
  *
-  * @returns TRUE on success
+  * @return TRUE on success
  */

 gboolean
@ -2192,7 +2192,7 @@ edit_load_menu_file (Dlg_head * h)
 /**
  * Close window with opened file.
  *
-  * @returns TRUE if file was closed.
+  * @return TRUE if file was closed.
  */

 gboolean
@ -2836,7 +2836,7 @@ edit_search_cmd (WEdit * edit, gboolean again)
 /**
  * Check if it's OK to close the file. If there are unsaved changes, ask user.
  *
-  * @returns TRUE if it's OK to exit, FALSE to continue editing.
+  * @return TRUE if it's OK to exit, FALSE to continue editing.
  */

 gboolean
--- a/src/editor/spell.c
+++ b/src/editor/spell.c
@ -129,7 +129,7 @@ static struct
 * Found the language name by language code. For example: en_US -> American English.
 *
 * @param code Short name of the language (ru, en, pl, uk, etc...)
- * @returns the language name
+ * @return language name
 */

 static const char *
@ -150,7 +150,7 @@ spell_decode_lang (const char *code)
 /**
 * Checks if aspell library and symbols are available.
 *
- * @returns FALSE or error
+ * @return FALSE or error
 */

 static gboolean
@ -342,7 +342,7 @@ aspell_clean (void)
 * Get array of available languages.
 *
 * @param lang_list Array of languages. Must be cleared before use
- * @returns language list length
+ * @return language list length
 */

 unsigned int
@ -406,7 +406,7 @@ aspell_array_clean (GArray * array)
 /**
 * Get the current language name.
 *
- * @returns Language name
+ * @return language name
 */

 const char *
@ -423,7 +423,7 @@ aspell_get_lang (void)
 * Set the language.
 *
 * @param lang Language name
- * @returns FALSE or error
+ * @return FALSE or error
 */

 gboolean
@ -469,7 +469,7 @@ aspell_set_lang (const char *lang)
 *
 * @param word Word for spell check
 * @param word_size Word size (in bytes)
- * @returns FALSE if word is not in the dictionary
+ * @return FALSE if word is not in the dictionary
 */

 gboolean
@ -490,7 +490,7 @@ aspell_check (const char *word, const int word_size)
 * @param suggest array of words to iterate through
 * @param word Word for spell check
 * @param word_size Word size (in bytes)
- * @returns count of suggests for the word
+ * @return count of suggests for the word
 */

 unsigned int
@ -533,7 +533,7 @@ aspell_suggest (GArray * suggest, const char *word, const int word_size)
 *
 * @param word Word for spell check
 * @param word_size  Word size (in bytes)
- * @returns FALSE or error
+ * @return FALSE or error
 */
 gboolean
 aspell_add_to_dict (const char *word, int word_size)
--- a/src/editor/spell_dialogs.c
+++ b/src/editor/spell_dialogs.c
@ -55,7 +55,7 @@
 * @param word Word for spell check
 * @param new_word Word to replace the incorrect word
 * @param suggest Array of suggests for current word
- * @returns code of pressed button
+ * @return code of pressed button
 */

 int
@ -150,7 +150,7 @@ spell_dialog_spell_suggest_show (WEdit * edit, const char *word, char **new_word
 * Show dialog to select language for spell check.
 *
 * @param languages Array of available languages
- * @returns name of choosed language
+ * @return name of choosed language
 */

 char *
--- a/src/filemanager/dir.c
+++ b/src/filemanager/dir.c
@ -138,7 +138,7 @@ clean_sort_keys (dir_list * list, int start, int count)
 * Increase directory list by RESIZE_STEPS
 *
 * @param list directory list
- * @returns FALSE = failure, TRUE = success
+ * @return FALSE on failure, TRUE on success
 */

 static gboolean
@ -160,7 +160,7 @@ grow_list (dir_list * list)
 /* --------------------------------------------------------------------------------------------- */
 /**
 * If you change handle_dirent then check also handle_path.
- * @returns -1 = failure, 0 = don't add, 1 = add to the list
+ * @return -1 = failure, 0 = don't add, 1 = add to the list
 */

 static int
--- a/src/filemanager/panel.c
+++ b/src/filemanager/panel.c
@ -3998,7 +3998,7 @@ panel_set_lwd (WPanel * panel, const char *path_str)
 /* --------------------------------------------------------------------------------------------- */
 /** Panel creation.
 * @param panel_name the name of the panel for setup retieving
- * @returns new instance of WPanel
+ * @return new instance of WPanel
 */

 WPanel *
@ -4015,7 +4015,7 @@ panel_new (const char *panel_name)
 * @param wpath the path of working panel directory. If path is NULL then panel will be created
 * for current directory
 *
- * @returns new instance of WPanel
+ * @return new instance of WPanel
 */

 WPanel *
--- a/src/help.c
+++ b/src/help.c
@ -161,7 +161,7 @@ search_string (const char *start, const char *text)
 /* --------------------------------------------------------------------------------------------- */
 /** Searches text in the buffer pointed by start.  Search ends
 * if the CHAR_NODE_END is found in the text.
- * @returns 0 on failure
+ * @return NULL on failure
 */

 static const char *
--- a/src/setup.c
+++ b/src/setup.c
@ -409,7 +409,7 @@ static const struct
 * @param subdir If not NULL, config is also searched in specified subdir.
 * @param config_file_name If relative, file if searched in standard paths.
 *
- * @returns Newly allocated string with config name or NULL if file is not found.
+ * @return newly allocated string with config name or NULL if file is not found.
 */

 static char *
--- a/src/vfs/sftpfs/file.c
+++ b/src/vfs/sftpfs/file.c
@ -225,7 +225,7 @@ sftpfs_fstat (void *data, struct stat *buf, GError ** error)
 * @param count data size
 * @param error pointer to the error handler
 *
- * @returns 0 on sucess, negative value otherwise
+ * @return 0 on sucess, negative value otherwise
 */

 ssize_t
@ -277,7 +277,7 @@ sftpfs_read_file (vfs_file_handler_t * file_handler, char *buffer, size_t count,
 * @param count        data size
 * @param error        pointer to the error handler
 *
- * @returns 0 on sucess, negative value otherwise
+ * @return 0 on sucess, negative value otherwise
 */

 ssize_t
@ -322,7 +322,7 @@ sftpfs_write_file (vfs_file_handler_t * file_handler, const char *buffer, size_t
 * @param file_handler    file data handler
 * @param error           pointer to the error handler
 *
- * @returns 0 on sucess, negative value otherwise
+ * @return 0 on sucess, negative value otherwise
 */

 int
@ -352,7 +352,7 @@ sftpfs_close_file (vfs_file_handler_t * file_handler, GError ** error)
 * @param whence         method of seek (at begin, at current, at end)
 * @param error          pointer to the error handler
 *
- * @returns 0 on sucess, negative value otherwise
+ * @return 0 on sucess, negative value otherwise
 */

 off_t