From 8f64d5d223a6ccc60f04e815355c9d3f216a4410 Mon Sep 17 00:00:00 2001
From: Vincent Sanders <vince@kyllikki.org>
Date: Sat, 8 Nov 2014 12:35:11 +0000
Subject: Improve Doxygen documentation

---
 amiga/search.c          |  2 +-
 atari/file.c            |  2 +-
 atari/plot/fontplot.c   | 16 ++++++++--------
 content/fetchers/file.c |  9 +++++++--
 desktop/gui_misc.h      |  1 +
 desktop/hotlist.h       |  2 +-
 gtk/search.c            |  4 ++--
 render/search.c         |  9 ++++++---
 render/search.h         | 31 ++++++++++++++++---------------
 riscos/mouse.h          |  4 ++--
 riscos/search.c         |  4 +++-
 riscos/sslcert.c        |  1 +
 utils/file.c            |  2 +-
 13 files changed, 50 insertions(+), 37 deletions(-)

diff --git a/amiga/search.c b/amiga/search.c
index daf2db121..77f0352be 100755
--- a/amiga/search.c
+++ b/amiga/search.c
@@ -86,7 +86,7 @@ struct gui_search_table *amiga_search_table = &search_table;
 /**
  * Change the displayed search status.
  *
- * \param found  search pattern matched in text
+ * \param gwin gui window to open search for.
  */
 void ami_search_open(struct gui_window *gwin)
 {
diff --git a/atari/file.c b/atari/file.c
index 8008e47c1..b6d465f91 100644
--- a/atari/file.c
+++ b/atari/file.c
@@ -48,7 +48,7 @@
  *                     NULL on input and if not NULL set to the total
  *                     output length on output.
  * @param[in] nelm The number of elements.
- * @param[in] ... The elements of the path as string pointers.
+ * @param[in] ap The elements of the path as string pointers.
  * @return NSERROR_OK and the complete path is written to str
  *         or error code on faliure.
  */
diff --git a/atari/plot/fontplot.c b/atari/plot/fontplot.c
index 3d5526bd4..97f3503cb 100644
--- a/atari/plot/fontplot.c
+++ b/atari/plot/fontplot.c
@@ -46,17 +46,17 @@ void dump_font_drivers(void)
 
 
 /**
- *	Create an new text plotter object
+ * Create an new text plotter object.
  *
- *	Available: "vdi", "freetype", "internal"
- *	\param vdihandle the vdi handle to act upon,
- *	\param name selector ID (string) of the font plotter.
- *	flags flags configration flags of the plotter,
- *	             available flags:
+ * Available: "vdi", "freetype", "internal"
+ *
+ * \param vdihandle the vdi handle to act upon,
+ * \param name selector ID (string) of the font plotter.
+ * \param flags configration flags of the plotter, available flags:
  *	             FONTPLOT_FLAG_MONOGLYPH - Enable 1 bit font plotting
- *	\param error set to != 0 when errors occur
+ * \param error set to != 0 when errors occur
  * \return the new font plotter instance on success, or NULL on failure.
-*/
+ */
 FONT_PLOTTER new_font_plotter(int vdihandle, char * name, unsigned long flags,
 		int * error)
 {
diff --git a/content/fetchers/file.c b/content/fetchers/file.c
index eced97f6f..d42e92a5b 100644
--- a/content/fetchers/file.c
+++ b/content/fetchers/file.c
@@ -497,9 +497,14 @@ static char *gen_nice_title(char *path)
 }
 
 /**
- * generate an output row of the directory listing.
+ * Generate an output row of the directory listing.
  *
- * @param ent current directory entry.
+ * \param ctx The file fetching context.
+ * \param ent current directory entry.
+ * \param even is the row an even row.
+ * \param buffer The output buffer.
+ * \param buffer_len The space available in the output buffer.
+ * \return NSERROR_OK or error code on faliure.
  */
 static nserror
 process_dir_ent(struct fetch_file_context *ctx,
diff --git a/desktop/gui_misc.h b/desktop/gui_misc.h
index 4664fc9dd..a35ee513f 100644
--- a/desktop/gui_misc.h
+++ b/desktop/gui_misc.h
@@ -76,6 +76,7 @@ struct gui_browser_table {
 	 * \param certs The certificate to be verified
 	 * \param num The number of certificates to be verified.
 	 * \param cb Callback upon user decision.
+	 * \param cbpw Context pointer passed to cb
 	 */
 	void (*cert_verify)(struct nsurl *url, const struct ssl_cert_info *certs, unsigned long num, nserror (*cb)(bool proceed, void *pw), void *cbpw);
 
diff --git a/desktop/hotlist.h b/desktop/hotlist.h
index 933f30b42..2733d589f 100644
--- a/desktop/hotlist.h
+++ b/desktop/hotlist.h
@@ -171,7 +171,7 @@ nserror hotlist_iterate(void *ctx,
  * Redraw the hotlist.
  *
  * \param x		X coordinate to render treeview at
- * \param x		Y coordinate to render treeview at
+ * \param y		Y coordinate to render treeview at
  * \param clip		Current clip rectangle (wrt tree origin)
  * \param ctx		Current redraw context
  */
diff --git a/gtk/search.c b/gtk/search.c
index 2d735bf77..9582e25b3 100644
--- a/gtk/search.c
+++ b/gtk/search.c
@@ -45,7 +45,7 @@
  * activate search forwards button in gui.
  *
  * \param active activate/inactivate
- * \param p the pointer sent to search_verify_new() / search_create_context()
+ * \param gw The gui window in which to activite the search button in.
  */
 static void nsgtk_search_set_forward_state(bool active, struct gui_window *gw)
 {
@@ -61,7 +61,7 @@ static void nsgtk_search_set_forward_state(bool active, struct gui_window *gw)
  * activate search back button in gui.
  *
  * \param active activate/inactivate
- * \param p the pointer sent to search_verify_new() / search_create_context()
+ * \param gw The gui window in which to activite the search button in.
  */
 static void nsgtk_search_set_back_state(bool active, struct gui_window *gw)
 {
diff --git a/render/search.c b/render/search.c
index f509f5890..7c2bd2def 100644
--- a/render/search.c
+++ b/render/search.c
@@ -268,9 +268,10 @@ static const char *find_pattern(const char *string, int s_len,
 /**
  * Add a new entry to the list of matches
  *
- * \param  start_idx  offset of match start within textual representation
- * \param  end_idx    offset of match end
- * \return pointer to added entry, NULL iff failed
+ * \param start_idx Offset of match start within textual representation
+ * \param end_idx   Offset of match end
+ * \param context   The search context to add the entry to.
+ * \return Pointer to added entry, NULL iff failed.
  */
 
 static struct list_entry *add_entry(unsigned start_idx, unsigned end_idx,
@@ -310,6 +311,7 @@ static struct list_entry *add_entry(unsigned start_idx, unsigned end_idx,
  * \param p_len     pattern length
  * \param cur       pointer to the current box
  * \param case_sens whether to perform a case sensitive search
+ * \param context   The search context to add the entry to.
  * \return true on success, false on memory allocation failure
  */
 static bool find_occurrences_html(const char *pattern, int p_len,
@@ -371,6 +373,7 @@ static bool find_occurrences_html(const char *pattern, int p_len,
  * \param p_len     pattern length
  * \param c         the content to be searched
  * \param case_sens wheteher to perform a case sensitive search
+ * \param context   The search context to add the entry to.
  * \return true on success, false on memory allocation failure
  */
 
diff --git a/render/search.h b/render/search.h
index a8354e77e..79d1ee3d3 100644
--- a/render/search.h
+++ b/render/search.h
@@ -29,13 +29,12 @@ struct search_context;
 /**
  * create a search_context
  *
- * \param c 	the content the search_context is connected to
- * \param type	the content type of c
- * \param callbacks the callbacks to modify appearance according to results
- * \param p 	the pointer to send to the callbacks
- * \return true for success
+ * \param c       The content the search_context is connected to
+ * \param type    The content type of c
+ * \param context A context pointer passed to the provider routines.
+ * \return A new search context or NULL on error.
  */
-struct search_context * search_create_context(struct content *c,
+struct search_context *search_create_context(struct content *c,
 				      content_type type, void *context);
 
 /**
@@ -46,11 +45,12 @@ void search_destroy_context(struct search_context *context);
 
 /**
  * Begins/continues the search process
- * Note that this may be called many times for a single search.
  *
- * \param bw the browser_window to search in
- * \param flags the flags forward/back etc
- * \param string the string to match
+ * \note that this may be called many times for a single search.
+ *
+ * \param context The search context in use.
+ * \param flags   The flags forward/back etc
+ * \param string  The string to match
  */
 void search_step(struct search_context *context, search_flags_t flags,
 		const char * string);
@@ -65,11 +65,12 @@ void search_show_all(bool all, struct search_context *context);
  * Determines whether any portion of the given text box should be
  * selected because it matches the current search string.
  *
- * \param  bw            browser window
- * \param  start_offset  byte offset within text of string to be checked
- * \param  end_offset    byte offset within text
- * \param  start_idx     byte offset within string of highlight start
- * \param  end_idx       byte offset of highlight end
+ * \param c            The content to hilight within.
+ * \param start_offset byte offset within text of string to be checked
+ * \param end_offset   byte offset within text
+ * \param start_idx    byte offset within string of highlight start
+ * \param end_idx      byte offset of highlight end
+ * \param context      The search context to hilight entries from.
  * \return true iff part of the box should be highlighted
  */
 bool search_term_highlighted(struct content *c,
diff --git a/riscos/mouse.h b/riscos/mouse.h
index 8a7405a2f..6bc5c13e1 100644
--- a/riscos/mouse.h
+++ b/riscos/mouse.h
@@ -17,8 +17,8 @@
  */
 
 
-/** \file mouse.h
- * Mouse dragging and tracking support (interface).
+/** \file
+ * Mouse dragging and tracking support interface for RISC OS.
  */
 
 #ifndef _NETSURF_RISCOS_MOUSE_H_
diff --git a/riscos/search.c b/riscos/search.c
index ff95430ce..60b37160a 100644
--- a/riscos/search.c
+++ b/riscos/search.c
@@ -193,11 +193,13 @@ bool ro_gui_search_click(wimp_pointer *pointer)
 
 /**
  * add search string to recent searches list
+ *
  * front is at liberty how to implement the bare notification
  * should normally store a strdup() of the string in
  * search_global_data.recent[];
  * core gives no guarantee of the integrity of the const char *
- * \param string search pattern
+ *
+ * \param search string search pattern
  * \param p the pointer sent to search_verify_new()
  */
 
diff --git a/riscos/sslcert.c b/riscos/sslcert.c
index 3ebf6b788..d8d94a32c 100644
--- a/riscos/sslcert.c
+++ b/riscos/sslcert.c
@@ -105,6 +105,7 @@ void ro_gui_cert_postinitialise(void)
  * \param certs The certificate to be verified
  * \param num The number of certificates to be verified.
  * \param cb Callback upon user decision.
+ * \param cbpw Context pointer passed to cb
  */
 void gui_cert_verify(nsurl *url,
 		const struct ssl_cert_info *certs, unsigned long num,
diff --git a/utils/file.c b/utils/file.c
index 83d29931a..00f8eefec 100644
--- a/utils/file.c
+++ b/utils/file.c
@@ -46,7 +46,7 @@
  *                     NULL on input and if not NULL set to the total
  *                     output length on output.
  * @param[in] nelm The number of elements.
- * @param[in] ... The elements of the path as string pointers.
+ * @param[in] ap The elements of the path as string pointers.
  * @return NSERROR_OK and the complete path is written to str
  *         or error code on faliure.
  */
-- 
cgit v1.2.3