From 55c8f041daa999ae32570d6fe4463c81550f96ba Mon Sep 17 00:00:00 2001 From: Ilia Maslakov Date: Fri, 31 Aug 2012 18:05:29 +0400 Subject: [PATCH] fixed doxygen documentation Signed-off-by: Ilia Maslakov --- doc/doxygen.cfg | 2 +- lib/hook.h | 2 +- lib/serialize.c | 2 +- lib/strutil.h | 17 +++++++- lib/strutil/strescape.c | 52 +++++++++++----------- lib/util.c | 5 ++- lib/util.h | 2 +- lib/utilunix.c | 15 +++++-- lib/vfs/path.c | 38 ++++++++++------ lib/vfs/vfs.c | 5 ++- lib/widget/history.h | 2 +- lib/widget/input.c | 3 +- lib/widget/input_complete.c | 2 +- src/editor/edit.c | 79 ++++++++++++++++++---------------- src/editor/spell.c | 2 +- src/filemanager/dir.c | 2 +- src/filemanager/file.c | 2 +- src/filemanager/panel.c | 16 +++++-- src/history.h | 2 +- src/setup.c | 12 +++--- src/vfs/sftpfs/config_parcer.c | 7 +-- src/vfs/sftpfs/file.c | 41 ++++++++++-------- 22 files changed, 184 insertions(+), 126 deletions(-) diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg index ae3f12c2f..07bc973ae 100644 --- a/doc/doxygen.cfg +++ b/doc/doxygen.cfg @@ -242,7 +242,7 @@ DIRECTORY_GRAPH = YES DOT_IMAGE_FORMAT = png DOT_PATH = $(DOT_PATH) DOTFILE_DIRS = -DOT_GRAPH_MAX_NODES = 50 +DOT_GRAPH_MAX_NODES = 550 MAX_DOT_GRAPH_DEPTH = 0 DOT_TRANSPARENT = NO DOT_MULTI_TARGETS = NO diff --git a/lib/hook.h b/lib/hook.h index e0ba02e19..0cd3f4669 100644 --- a/lib/hook.h +++ b/lib/hook.h @@ -1,4 +1,4 @@ -/** \file util.h +/** \file lib/hook.h * \brief Header: hooks */ diff --git a/lib/serialize.c b/lib/serialize.c index c47223e12..84889284c 100644 --- a/lib/serialize.c +++ b/lib/serialize.c @@ -23,7 +23,7 @@ along with this program. If not, see . */ -/** \file serialize.c +/** \file lib/serialize.c * \brief Source: serialize/unserialize functionality for INI-like formats. */ diff --git a/lib/strutil.h b/lib/strutil.h index 0f9e94915..cf0a0d107 100644 --- a/lib/strutil.h +++ b/lib/strutil.h @@ -527,9 +527,15 @@ int str_verscmp (const char *s1, const char *s2); void str_msg_term_size (const char *text, int *lines, int *columns); /** - skip first needle's in haystack and returns pointer to - needle (or NULL if not found). + * skip first needle's in haystack + * + * @param haystack pointer to string + * @param needle pointer to string + * @param skip_count skip first bytes + * + * @returns 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); /*** inline functions ****************************************************************************/ @@ -554,7 +560,14 @@ str_replace (char *s, char from, char to) * * We can't use str*cpy funs here: * http://kerneltrap.org/mailarchive/openbsd-misc/2008/5/27/1951294 + * + * @param dest pointer to string + * @param src pointer to string + * + * @returns a newly allocated string + * */ + static inline char * str_move (char *dest, const char *src) { diff --git a/lib/strutil/strescape.c b/lib/strutil/strescape.c index e99191c94..440420c31 100644 --- a/lib/strutil/strescape.c +++ b/lib/strutil/strescape.c @@ -160,16 +160,15 @@ strutils_unescape (const char *src, gsize src_len, const char *unescaped_chars, /* --------------------------------------------------------------------------------------------- */ -/** To be compatible with the general posix command lines we have to escape - strings for the command line - - \param src - string for escaping - - \returns - return escaped string (which needs to be freed later) - or NULL when NULL string is passed. +/** + * To be compatible with the general posix command lines we have to escape + * strings for the command line + * + * @param src string for escaping + * + * @returns escaped string (which needs to be freed later) or NULL when NULL string is passed. */ + char * strutils_shell_escape (const char *src) { @@ -194,15 +193,15 @@ strutils_regex_escape (const char *src) /* --------------------------------------------------------------------------------------------- */ -/** Unescape paths or other strings for e.g the internal cd - shell-unescape within a given buffer (writing to it!) - - \param text - string for unescaping - - \returns - return unescaped string (which needs to be freed) +/** + * Unescape paths or other strings for e.g the internal cd + * shell-unescape within a given buffer (writing to it!) + * + * @param text string for unescaping + * + * @returns unescaped string (which needs to be freed) */ + char * strutils_shell_unescape (const char *text) { @@ -226,18 +225,15 @@ strutils_regex_unescape (const char *text) /* --------------------------------------------------------------------------------------------- */ -/** Check if char in pointer contain escape'd chars - - \param start - string for checking - - \param current - pointer to checked character - - \returns - return TRUE if string contain escaped chars - otherwise return FALSE +/** + * Check if char in pointer contain escape'd chars + * + * @param start string for checking + * @param current pointer to checked character + * + * @returns TRUE if string contain escaped chars otherwise return FALSE */ + gboolean strutils_is_char_escaped (const char *start, const char *current) { diff --git a/lib/util.c b/lib/util.c index a56e2c83e..127eed836 100644 --- a/lib/util.c +++ b/lib/util.c @@ -31,7 +31,7 @@ along with this program. If not, see . */ -/** \file +/** \file lib/util.c * \brief Source: various utilities */ @@ -915,6 +915,9 @@ wipe_password (char *passwd) /* --------------------------------------------------------------------------------------------- */ /** * Convert "\E" -> esc character and ^x to control-x key and ^^ to ^ key + * + * @param p pointer to string + * * @returns a newly allocated string */ diff --git a/lib/util.h b/lib/util.h index f64f45ce2..176d62f56 100644 --- a/lib/util.h +++ b/lib/util.h @@ -1,4 +1,4 @@ -/** \file util.h +/** \file lib/util.h * \brief Header: various utilities */ diff --git a/lib/utilunix.c b/lib/utilunix.c index 382161057..92993163f 100644 --- a/lib/utilunix.c +++ b/lib/utilunix.c @@ -280,9 +280,13 @@ my_system (int flags, const char *shell, const char *command) /* --------------------------------------------------------------------------------------------- */ + /** * Perform tilde expansion if possible. - * Always return a newly allocated string, even if it's unchanged. + * + * @param directory pointer to the path + * + * @returns a newly allocated string, even if it's unchanged. */ char * @@ -376,9 +380,12 @@ open_error_pipe (void) /* --------------------------------------------------------------------------------------------- */ /** - * Returns true if an error was displayed - * error: -1 - ignore errors, 0 - display warning, 1 - display error - * text is prepended to the error message from the pipe + * Close a pipe + * + * @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 */ int diff --git a/lib/vfs/path.c b/lib/vfs/path.c index 5b85c1d16..6d1ebcec3 100644 --- a/lib/vfs/path.c +++ b/lib/vfs/path.c @@ -597,15 +597,6 @@ vfs_path_strip_home (const char *dir) /* --------------------------------------------------------------------------------------------- */ /*** public functions ****************************************************************************/ /* --------------------------------------------------------------------------------------------- */ -/** - * Convert first elements_count elements from vfs_path_t to string representation with flags. - * - * @param vpath pointer to vfs_path_t object - * @param elements_count count of first elements for convert - * @param flags flags for converter - * - * @return pointer to newly created string. - */ #define vfs_append_from_path(appendfrom, is_relative) \ { \ @@ -625,6 +616,16 @@ vfs_path_strip_home (const char *dir) } \ } +/** + * Convert first elements_count elements from vfs_path_t to string representation with flags. + * + * @param vpath pointer to vfs_path_t object + * @param elements_count count of first elements for convert + * @param flags for converter + * + * @return pointer to newly created string. + */ + char * vfs_path_to_str_flags (const vfs_path_t * vpath, int elements_count, vfs_path_flag_t flags) { @@ -1031,6 +1032,9 @@ vfs_prefix_to_class (const char *prefix) } /* --------------------------------------------------------------------------------------------- */ + +#ifdef HAVE_CHARSET + /** * Check if need cleanup charset converter for vfs_path_element_t * @@ -1038,7 +1042,7 @@ vfs_prefix_to_class (const char *prefix) * * @return TRUE if need cleanup converter or FALSE otherwise */ -#ifdef HAVE_CHARSET + gboolean vfs_path_element_need_cleanup_converter (const vfs_path_element_t * element) { @@ -1047,13 +1051,14 @@ vfs_path_element_need_cleanup_converter (const vfs_path_element_t * element) #endif /* --------------------------------------------------------------------------------------------- */ + /** * Serialize vfs_path_t object to string * * @param vpath data for serialization * @param error contain pointer to object for handle error code and message * - * @return serialized vpath as newly allocated string + * @returns serialized vpath as newly allocated string */ char * @@ -1189,6 +1194,7 @@ vfs_path_deserialize (const char *data, GError ** error) /** * Build vfs_path_t object from arguments. * + * @param first_element of path * @param ... path tokens, terminated by NULL * * @return newly allocated vfs_path_t object @@ -1217,6 +1223,7 @@ vfs_path_build_filename (const char *first_element, ...) * Append tokens to path object * * @param vpath path object + * @param first_element of path * @param ... NULL-terminated strings * * @return newly allocated path object @@ -1250,6 +1257,7 @@ vfs_path_append_new (const vfs_path_t * vpath, const char *first_element, ...) /** * Append vpath_t tokens to path object * + * @param first_vpath vpath objects * @param ... NULL-terminated vpath objects * * @return newly allocated path object @@ -1288,6 +1296,7 @@ vfs_path_append_vpath_new (const vfs_path_t * first_vpath, ...) } /* --------------------------------------------------------------------------------------------- */ + /** * get tockens count in path. * @@ -1325,6 +1334,7 @@ vfs_path_tokens_count (const vfs_path_t * vpath) } /* --------------------------------------------------------------------------------------------- */ + /** * Get subpath by tokens * @@ -1435,12 +1445,14 @@ vfs_path_vtokens_get (const vfs_path_t * vpath, ssize_t start_position, ssize_t } /* --------------------------------------------------------------------------------------------- */ + /** - * Build URL parameters (such as user:pass@host:port) from one path element object + * Build URL parameters (such as user:pass @ host:port) from one path element object * * @param element path element + * @param keep_password TRUE or FALSE * - * @return newly allocated string + * @returns newly allocated string */ char * diff --git a/lib/vfs/vfs.c b/lib/vfs/vfs.c index 2f480e378..7397eec46 100644 --- a/lib/vfs/vfs.c +++ b/lib/vfs/vfs.c @@ -622,13 +622,14 @@ vfs_change_encoding (vfs_path_t * vpath, const char *encoding) * Preallocate space for file in new place for ensure that file * will be fully copied with less fragmentation. * - * @param dest_desc mc VFS file handler + * @param dest_vfs_fd mc VFS file handler * @param src_fsize source file size * @param dest_fsize destination file size (if destination exists, otherwise should be 0) * - * @return 0 if success and non-zero otherwise. + * @returns 0 if success and non-zero otherwise. * Note: function doesn't touch errno global variable. */ + int vfs_preallocate (int dest_vfs_fd, off_t src_fsize, off_t dest_fsize) { diff --git a/lib/widget/history.h b/lib/widget/history.h index 729b3c6ea..fca4d6968 100644 --- a/lib/widget/history.h +++ b/lib/widget/history.h @@ -1,5 +1,5 @@ -/** \file history.h +/** \file lib/widget/history.h * \brief Header: save, load and show history */ diff --git a/lib/widget/input.c b/lib/widget/input.c index 9b4105588..79a1a2ede 100644 --- a/lib/widget/input.c +++ b/lib/widget/input.c @@ -209,7 +209,8 @@ do_show_hist (WInput * in) } /* --------------------------------------------------------------------------------------------- */ -/** Strip password from incomplete url (just user:pass@host without VFS prefix). +/** + * Strip password from incomplete url (just user:pass@host without VFS prefix). * * @param url partial URL * @return newly allocated string without password diff --git a/lib/widget/input_complete.c b/lib/widget/input_complete.c index 3840c41bd..8b671929d 100644 --- a/lib/widget/input_complete.c +++ b/lib/widget/input_complete.c @@ -25,7 +25,7 @@ along with this program. If not, see . */ -/** \file complete.c +/** \file lib/widget/input_complete.c * \brief Source: Input line filename/username/hostname/variable/command completion */ diff --git a/src/editor/edit.c b/src/editor/edit.c index 1da96c1c3..c702c1fd5 100644 --- a/src/editor/edit.c +++ b/src/editor/edit.c @@ -2406,44 +2406,49 @@ edit_set_codeset (WEdit * edit) /* --------------------------------------------------------------------------------------------- */ + /** - Recording stack for undo: - The following is an implementation of a compressed stack. Identical - pushes are recorded by a negative prefix indicating the number of times the - same char was pushed. This saves space for repeated curs-left or curs-right - delete etc. - - eg: - - pushed: stored: - - a - b a - b -3 - b b - c --> -4 - c c - c d - c - d - - If the stack long int is 0-255 it represents a normal insert (from a backspace), - 256-512 is an insert ahead (from a delete), If it is betwen 600 and 700 it is one - of the cursor functions #define'd in edit-impl.h. 1000 through 700'000'000 is to - set edit->mark1 position. 700'000'000 through 1400'000'000 is to set edit->mark2 - position. - - The only way the cursor moves or the buffer is changed is through the routines: - insert, backspace, insert_ahead, delete, and cursor_move. - These record the reverse undo movements onto the stack each time they are - called. - - Each key press results in a set of actions (insert; delete ...). So each time - a key is pressed the current position of start_display is pushed as - KEY_PRESS + start_display. Then for undoing, we pop until we get to a number - over KEY_PRESS. We then assign this number less KEY_PRESS to start_display. So undo - tracks scrolling and key actions exactly. (KEY_PRESS is about (2^31) * (2/3) = 1400'000'000) - + * Recording stack for undo: + * The following is an implementation of a compressed stack. Identical + * pushes are recorded by a negative prefix indicating the number of times the + * same char was pushed. This saves space for repeated curs-left or curs-right + * delete etc. + * + * eg: + * + * pushed: stored: + * + * a + * b a + * b -3 + * b b + * c --> -4 + * c c + * c d + * c + * d + * + * If the stack long int is 0-255 it represents a normal insert (from a backspace), + * 256-512 is an insert ahead (from a delete), If it is betwen 600 and 700 it is one + * of the cursor functions define'd in edit-impl.h. 1000 through 700'000'000 is to + * set edit->mark1 position. 700'000'000 through 1400'000'000 is to set edit->mark2 + * position. + * + * The only way the cursor moves or the buffer is changed is through the routines: + * insert, backspace, insert_ahead, delete, and cursor_move. + * These record the reverse undo movements onto the stack each time they are + * called. + * + * Each key press results in a set of actions (insert; delete ...). So each time + * a key is pressed the current position of start_display is pushed as + * KEY_PRESS + start_display. Then for undoing, we pop until we get to a number + * over KEY_PRESS. We then assign this number less KEY_PRESS to start_display. So undo + * tracks scrolling and key actions exactly. (KEY_PRESS is about (2^31) * (2/3) = 1400'000'000) + * + * + * + * @param edit editor object + * @param c code of the action */ void diff --git a/src/editor/spell.c b/src/editor/spell.c index 5b4ac6ff1..809990c23 100644 --- a/src/editor/spell.c +++ b/src/editor/spell.c @@ -422,7 +422,7 @@ aspell_get_lang (void) /** * Set the language. * - * @param Language name + * @param lang Language name * @returns FALSE or error */ diff --git a/src/filemanager/dir.c b/src/filemanager/dir.c index 062cc52b0..afc63d329 100644 --- a/src/filemanager/dir.c +++ b/src/filemanager/dir.c @@ -21,7 +21,7 @@ along with this program. If not, see . */ -/** \file dir.c +/** \file src/filemanager/dir.c * \brief Source: directory routines */ diff --git a/src/filemanager/file.c b/src/filemanager/file.c index 7647a7ca6..d4fd7b9b0 100644 --- a/src/filemanager/file.c +++ b/src/filemanager/file.c @@ -43,7 +43,7 @@ * operations. */ -/** \file file.c +/** \file src/filemanager/file.c * \brief Source: file management */ diff --git a/src/filemanager/panel.c b/src/filemanager/panel.c index a1d022439..f427504d8 100644 --- a/src/filemanager/panel.c +++ b/src/filemanager/panel.c @@ -4005,9 +4005,13 @@ panel_new (const char *panel_name) } /* --------------------------------------------------------------------------------------------- */ -/** Panel creation for specified directory. +/** + * Panel creation for specified directory. + * * @param panel_name specifies the name of the panel for setup retieving - * @param the path of working panel directory. If path is NULL then panel will be created for current directory + * @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 */ @@ -4478,12 +4482,14 @@ panel_set_sort_order (WPanel * panel, const panel_field_t * sort_order) } /* --------------------------------------------------------------------------------------------- */ + +#ifdef HAVE_CHARSET + /** * Change panel encoding. * @param panel WPanel object */ -#ifdef HAVE_CHARSET void panel_change_encoding (WPanel * panel) { @@ -4584,6 +4590,7 @@ remove_encoding_from_path (const vfs_path_t * vpath) #endif /* HAVE_CHARSET */ /* --------------------------------------------------------------------------------------------- */ + /** * This routine reloads the directory in both panels. It tries to * select current_file in current_panel and other_file in other_panel. @@ -4592,6 +4599,9 @@ remove_encoding_from_path (const vfs_path_t * vpath) * * if force_update has the UP_ONLY_CURRENT bit toggled on, then it * will not reload the other panel. + * + * @param flags for reload panel + * @param current_file name of the current file */ void diff --git a/src/history.h b/src/history.h index e80115d60..7a8d73fa2 100644 --- a/src/history.h +++ b/src/history.h @@ -1,4 +1,4 @@ -/** \file history.h +/** \file src/history.h * \brief Header: defines history section names */ diff --git a/src/setup.c b/src/setup.c index 524a4be2f..2ef45e32e 100644 --- a/src/setup.c +++ b/src/setup.c @@ -369,12 +369,14 @@ static const struct /* --------------------------------------------------------------------------------------------- */ /** - Get name of config file. + * Get name of config file. + * + * @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. + */ - @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. -*/ static char * load_setup_get_full_config_name (const char *subdir, const char *config_file_name) { diff --git a/src/vfs/sftpfs/config_parcer.c b/src/vfs/sftpfs/config_parcer.c index 0b780cb7d..c2ce1b55b 100644 --- a/src/vfs/sftpfs/config_parcer.c +++ b/src/vfs/sftpfs/config_parcer.c @@ -127,6 +127,10 @@ sftpfs_correct_file_name (const char *filename) } /* --------------------------------------------------------------------------------------------- */ + +#define POINTER_TO_STRUCTURE_MEMBER(type) \ + ((type) ((void *) config_entity + (off_t) config_variables[i].offset)) + /** * Parse string and filling one config entity by parsed data. * @@ -134,9 +138,6 @@ sftpfs_correct_file_name (const char *filename) * @param buffer string for parce */ -#define POINTER_TO_STRUCTURE_MEMBER(type) \ - ((type) ((void *) config_entity + (off_t) config_variables[i].offset)) - static void sftpfs_fill_config_entity_from_string (sftpfs_ssh_config_entity_t * config_entity, char *buffer) { diff --git a/src/vfs/sftpfs/file.c b/src/vfs/sftpfs/file.c index b93c79b21..fb8cbac28 100644 --- a/src/vfs/sftpfs/file.c +++ b/src/vfs/sftpfs/file.c @@ -220,11 +220,12 @@ sftpfs_fstat (void *data, struct stat *buf, GError ** error) /** * Read up to 'count' bytes from the file descriptor 'file_handler' to the buffer starting at 'buffer'. * - * @param data file data handler + * @param file_handler file data handler * @param buffer buffer for data - * @param count data size - * @param error pointer to the error handler - * @return 0 if sucess, negative value otherwise + * @param count data size + * @param error pointer to the error handler + * + * @returns 0 on sucess, negative value otherwise */ ssize_t @@ -267,14 +268,16 @@ sftpfs_read_file (vfs_file_handler_t * file_handler, char *buffer, size_t count, } /* --------------------------------------------------------------------------------------------- */ + /** * Write up to 'count' bytes from the buffer starting at 'buffer' to the descriptor 'file_handler'. * - * @param data file data handler - * @param buffer buffer for data - * @param count data size - * @param error pointer to the error handler - * @return 0 if sucess, negative value otherwise + * @param file_handler file data handler + * @param buffer buffer for data + * @param count data size + * @param error pointer to the error handler + * + * @returns 0 on sucess, negative value otherwise */ ssize_t @@ -312,12 +315,14 @@ sftpfs_write_file (vfs_file_handler_t * file_handler, const char *buffer, size_t } /* --------------------------------------------------------------------------------------------- */ + /** * Close a file descriptor. * - * @param data file data handler - * @param error pointer to the error handler - * @return 0 if sucess, negative value otherwise + * @param file_handler file data handler + * @param error pointer to the error handler + * + * @returns 0 on sucess, negative value otherwise */ int @@ -338,14 +343,16 @@ sftpfs_close_file (vfs_file_handler_t * file_handler, GError ** error) } /* --------------------------------------------------------------------------------------------- */ + /** * Reposition the offset of the open file associated with the file descriptor. * - * @param data file data handler - * @param offset file offset - * @param whence method of seek (at begin, at current, at end) - * @param error pointer to the error handler - * @return 0 if sucess, negative value otherwise + * @param file_handler file data handler + * @param offset file offset + * @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 */ off_t