From 34b6fffc33139b38b4301d4283d2435f8d50328e Mon Sep 17 00:00:00 2001 From: Moritz Lipp Date: Wed, 8 Feb 2012 15:30:13 +0100 Subject: [PATCH] Update documentation --- bookmarks.h | 2 +- callbacks.h | 15 ++++++++++----- config.h | 3 ++- database.h | 13 ++++++++++--- document.h | 47 +++++++++++++++++++++++++++++++++++------------ render.h | 2 +- utils.h | 5 +++-- zathura.h | 2 ++ 8 files changed, 64 insertions(+), 25 deletions(-) diff --git a/bookmarks.h b/bookmarks.h index 34bfe84..7cd2698 100644 --- a/bookmarks.h +++ b/bookmarks.h @@ -49,7 +49,7 @@ void zathura_bookmark_free(zathura_bookmark_t* bookmark); * Load bookmarks for a specific file. * @param zathura The zathura instance. * @param file The file. - * @param true on success, false otherwise + * @return true on success, false otherwise */ bool zathura_bookmarks_load(zathura_t* zathura, const gchar* file); diff --git a/callbacks.h b/callbacks.h index 79ccaff..e49f46e 100644 --- a/callbacks.h +++ b/callbacks.h @@ -14,7 +14,7 @@ * * @param widget The gtk window of zathura * @param data NULL - * @return TRUE + * @return true if no error occured and the event has been handled */ gboolean cb_destroy(GtkWidget* widget, gpointer data); @@ -38,9 +38,13 @@ void cb_view_vadjustment_value_changed(GtkAdjustment *adjustment, gpointer data) * variable changes * * @param session The current girara session - * @param setting The "pages-per-row" setting + * @param name The name of the row + * @param type The settings type + * @param value The value + * @param data Custom data */ -void cb_pages_per_row_value_changed(girara_session_t* GIRARA_UNUSED(session), const char* GIRARA_UNUSED(name), girara_setting_type_t GIRARA_UNUSED(type), void* value, void* data); +void cb_pages_per_row_value_changed(girara_session_t* session, const char* name, + girara_setting_type_t type, void* value, void* data); /** * Called when an index element is activated (e.g.: double click) @@ -58,7 +62,7 @@ void cb_index_row_activated(GtkTreeView* tree_view, GtkTreePath* path, * * @param entry The dialog inputbar * @param session The girara session - * @return TRUE + * @return true if no error occured and the event has been handled */ bool cb_sc_follow(GtkEntry* entry, girara_session_t* session); @@ -71,6 +75,7 @@ bool cb_sc_follow(GtkEntry* entry, girara_session_t* session); * @param event The monitor event * @param session The girara session */ -void cb_file_monitor(GFileMonitor* monitor, GFile* file, GFile* other_file, GFileMonitorEvent event, girara_session_t* session); +void cb_file_monitor(GFileMonitor* monitor, GFile* file, GFile* other_file, + GFileMonitorEvent event, girara_session_t* session); #endif // CALLBACKS_H diff --git a/config.h b/config.h index 3e30f87..4587468 100644 --- a/config.h +++ b/config.h @@ -11,13 +11,14 @@ /** * This function loads the default values of the configuration * - * @param zathura the zathura session + * @param zathura The zathura session */ void config_load_default(zathura_t* zathura); /** * Loads and evaluates a configuration file * + * @param zathura The zathura session * @param path Path to the configuration file */ void config_load_file(zathura_t* zathura, char* path); diff --git a/database.h b/database.h index 71a2b83..54f5f2b 100644 --- a/database.h +++ b/database.h @@ -11,19 +11,22 @@ /** * Initialize database system. - * @param path Path to the directory where the database file should be located. + * + * @param dir Path to the directory where the database file should be located. * @return A valid zathura_database_t instance or NULL on failure */ zathura_database_t* zathura_db_init(const char* dir); /** * Free database instance. - * @param The database instance to free. + * + * @param db The database instance to free. */ void zathura_db_free(zathura_database_t* db); /** * Add or update bookmark in the database. + * * @param db The database instance * @param file The file to which the bookmark belongs to. * @param bookmark The bookmark instance. @@ -34,9 +37,10 @@ bool zathura_db_add_bookmark(zathura_database_t* db, const char* file, /** * Add or update bookmark in the database. + * * @param db The database instance * @param file The file to which the bookmark belongs to. - * @param bookmark The bookmark instance. + * @param id The id of the bookmark * @return true on success, false otherwise */ bool zathura_db_remove_bookmark(zathura_database_t* db, const char* file, const @@ -44,6 +48,7 @@ bool zathura_db_remove_bookmark(zathura_database_t* db, const char* file, const /** * Loads all bookmarks from the database belonging to a specific file. + * * @param db The database instance. * @param file The file for which the bookmarks should be loaded. * @return List of zathura_bookmark_t* or NULL on failure. @@ -53,6 +58,7 @@ girara_list_t* zathura_db_load_bookmarks(zathura_database_t* db, const char* /** * Set file info (last site, ...) in the database. + * * @param db The database instance * @param file The file to which the file info belongs to. * @param page The last page. @@ -64,6 +70,7 @@ bool zathura_db_set_fileinfo(zathura_database_t* db, const char* file, unsigned int page, int offset, double scale); /* Get file info (last site, ...) from the database. + * * @param db The database instance * @param file The file to which the file info belongs to. * @param page The last page. diff --git a/document.h b/document.h index a1499db..21947fd 100644 --- a/document.h +++ b/document.h @@ -97,9 +97,9 @@ zathura_image_buffer_t* zathura_image_buffer_create(unsigned int width, unsigned /** * Frees the image buffer * - * @param zathura_image_buffer_t + * @param buffer The image buffer */ -void zathura_image_buffer_free(zathura_image_buffer_t*); +void zathura_image_buffer_free(zathura_image_buffer_t* buffer); /** * Rectangle structure. @@ -315,6 +315,7 @@ void zathura_document_plugin_free(zathura_document_plugin_t* plugin); /** * Open the document * + * @param zathura Zathura object * @param path Path to the document * @param password Password of the document or NULL * @return The document object @@ -326,7 +327,8 @@ zathura_document_t* zathura_document_open(zathura_t* zathura, const char* path, * Free the document * * @param document - * @return See \ref zathura_plugin_error_t + * @return ZATHURA_PLUGIN_ERROR_OK when no error occured, otherwise see + * zathura_plugin_error_t */ zathura_plugin_error_t zathura_document_free(zathura_document_t* document); @@ -335,7 +337,8 @@ zathura_plugin_error_t zathura_document_free(zathura_document_t* document); * * @param document The document object * @param path Path for the saved file - * @return See \ref zathura_plugin_error_t + * @return ZATHURA_PLUGIN_ERROR_OK when no error occured, otherwise see + * zathura_plugin_error_t */ zathura_plugin_error_t zathura_document_save_as(zathura_document_t* document, const char* path); @@ -343,6 +346,8 @@ zathura_plugin_error_t zathura_document_save_as(zathura_document_t* document, co * Generate the document index * * @param document The document object + * @param error Set to an error value (see \ref zathura_plugin_error_t) if an + * error occured * @return Generated index */ @@ -352,6 +357,8 @@ girara_tree_node_t* zathura_document_index_generate(zathura_document_t* document * Get list of attachments * * @param document The document object + * @param error Set to an error value (see \ref zathura_plugin_error_t) if an + * error occured * @return List of attachments */ girara_list_t* zathura_document_attachments_get(zathura_document_t* document, zathura_plugin_error_t* error); @@ -362,7 +369,8 @@ girara_list_t* zathura_document_attachments_get(zathura_document_t* document, za * @param document The document objects * @param attachment name of the attachment * @param file the target filename - * @return true on success, false otherwise + * @return ZATHURA_PLUGIN_ERROR_OK when no error occured, otherwise see + * zathura_plugin_error_t */ zathura_plugin_error_t zathura_document_attachment_save(zathura_document_t* document, const char* attachment, const char* file); @@ -371,6 +379,8 @@ zathura_plugin_error_t zathura_document_attachment_save(zathura_document_t* docu * * @param document The zathura document * @param meta The information field + * @param error Set to an error value (see \ref zathura_plugin_error_t) if an + * error occured * @return String or NULL if information could not be retreived */ char* zathura_document_meta_get(zathura_document_t* document, zathura_document_meta_t meta, zathura_plugin_error_t* error); @@ -380,6 +390,8 @@ char* zathura_document_meta_get(zathura_document_t* document, zathura_document_m * * @param document The document * @param page_id Page number + * @param error Set to an error value (see \ref zathura_plugin_error_t) if an + * error occured * @return Page object or NULL if an error occured */ zathura_page_t* zathura_page_get(zathura_document_t* document, unsigned int page_id, zathura_plugin_error_t* error); @@ -388,7 +400,8 @@ zathura_page_t* zathura_page_get(zathura_document_t* document, unsigned int page * Frees the page object * * @param page The page object - * @return true if no error occured, otherwise false + * @return ZATHURA_PLUGIN_ERROR_OK when no error occured, otherwise see + * zathura_plugin_error_t */ zathura_plugin_error_t zathura_page_free(zathura_page_t* page); @@ -397,6 +410,8 @@ zathura_plugin_error_t zathura_page_free(zathura_page_t* page); * * @param page The page object * @param text Search item + * @param error Set to an error value (see \ref zathura_plugin_error_t) if an + * error occured * @return List of results */ girara_list_t* zathura_page_search_text(zathura_page_t* page, const char* text, zathura_plugin_error_t* error); @@ -405,6 +420,8 @@ girara_list_t* zathura_page_search_text(zathura_page_t* page, const char* text, * Get page links * * @param page The page object + * @param error Set to an error value (see \ref zathura_plugin_error_t) if an + * error occured * @return List of links */ girara_list_t* zathura_page_links_get(zathura_page_t* page, zathura_plugin_error_t* error); @@ -413,7 +430,8 @@ girara_list_t* zathura_page_links_get(zathura_page_t* page, zathura_plugin_error * Free page links * * @param list List of links - * @return true if no error occured, otherwise false + * @return ZATHURA_PLUGIN_ERROR_OK when no error occured, otherwise see + * zathura_plugin_error_t */ zathura_plugin_error_t zathura_page_links_free(girara_list_t* list); @@ -421,6 +439,8 @@ zathura_plugin_error_t zathura_page_links_free(girara_list_t* list); * Get list of form fields * * @param page The page object + * @param error Set to an error value (see \ref zathura_plugin_error_t) if an + * error occured * @return List of form fields */ girara_list_t* zathura_page_form_fields_get(zathura_page_t* page, zathura_plugin_error_t* error); @@ -429,8 +449,8 @@ girara_list_t* zathura_page_form_fields_get(zathura_page_t* page, zathura_plugin * Free list of form fields * * @param list List of form fields - * @param error See \ref zathura_plugin_error_t - * @return true if no error occured, otherwise false + * @return ZATHURA_PLUGIN_ERROR_OK when no error occured, otherwise see + * zathura_plugin_error_t */ zathura_plugin_error_t zathura_page_form_fields_free(girara_list_t* list); @@ -438,7 +458,8 @@ zathura_plugin_error_t zathura_page_form_fields_free(girara_list_t* list); * Get list of images * * @param page Page - * @param error See \ref zathura_plugin_error_t + * @param error Set to an error value (see \ref zathura_plugin_error_t) if an + * error occured * @return List of images or NULL if an error occured */ girara_list_t* zathura_page_images_get(zathura_page_t* page, zathura_plugin_error_t* error); @@ -449,7 +470,8 @@ girara_list_t* zathura_page_images_get(zathura_page_t* page, zathura_plugin_erro * @param page Page * @param image The image * @param file Path to the file - * @return See \ref zathura_plugin_error_t + * @return ZATHURA_PLUGIN_ERROR_OK when no error occured, otherwise see + * zathura_plugin_error_t */ zathura_plugin_error_t zathura_page_image_save(zathura_page_t* page, zathura_image_t* image, const char* file); @@ -459,7 +481,8 @@ zathura_plugin_error_t zathura_page_image_save(zathura_page_t* page, zathura_ima * @param page The page object * @param cairo Cairo object * @param printing render for printing - * @return See \ref zathura_plugin_error_t + * @return ZATHURA_PLUGIN_ERROR_OK when no error occured, otherwise see + * zathura_plugin_error_t */ zathura_plugin_error_t zathura_page_render(zathura_page_t* page, cairo_t* cairo, bool printing); diff --git a/render.h b/render.h index dbfabd0..955ccb3 100644 --- a/render.h +++ b/render.h @@ -22,7 +22,7 @@ struct render_thread_s /** * This function initializes a render thread * - * @param Zathura object + * @param zathura object * @return The render thread object or NULL if an error occured */ render_thread_t* render_init(zathura_t* zathura); diff --git a/utils.h b/utils.h index e94613f..46d415e 100644 --- a/utils.h +++ b/utils.h @@ -57,8 +57,8 @@ bool execute_command(char* const argv[], char** output); * object. * * @param model The tree model - * @param tree_it The Tree iterator - * @param list_it The index list iterator + * @param parent The tree iterator parent + * @param tree The Tree iterator */ void document_index_build(GtkTreeModel* model, GtkTreeIter* parent, girara_tree_node_t* tree); @@ -67,6 +67,7 @@ void document_index_build(GtkTreeModel* model, GtkTreeIter* parent, girara_tree_ * well as to the left side of it. The result has to be freed. * * @param page The Page + * @param offset Applied offset * @return The calculated offset or NULL if an error occured */ void page_calculate_offset(zathura_page_t* page, page_offset_t* offset); diff --git a/zathura.h b/zathura.h index 8df4836..c769474 100644 --- a/zathura.h +++ b/zathura.h @@ -160,6 +160,7 @@ bool document_close(zathura_t* zathura); * Opens the page with the given number * * @param zathura The zathura session + * @param page_id The id of the page that should be set * @return If no error occured true, otherwise false, is returned. */ bool page_set(zathura_t* zathura, unsigned int page_id); @@ -168,6 +169,7 @@ bool page_set(zathura_t* zathura, unsigned int page_id); * Opens the page with the given number (delayed) * * @param zathura The zathura session + * @param page_id The id of the page that should be set * @return If no error occured true, otherwise false, is returned. */ bool page_set_delayed(zathura_t* zathura, unsigned int page_id);