Update documentation

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);
 

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

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);

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.

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 ZATHURA_PLUGIN_ERROR_OK when no error occured, otherwise see
- * @return true if no error occured, otherwise false
+ *    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);
 

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);

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 parent The tree iterator parent
- * @param list_it The index list iterator
+ * @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);

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);