Fix Gtk-Doc comment notation.

Seeing lots of what I assume to be doxygen syntax in comment blocks.

14 files changed, 143 insertions, 97 deletions

diff --git a/calendar/gui/alarm-notify/alarm-queue.c b/calendar/gui/alarm-notify/alarm-queue.c
index 3bdd60a1b7..3f8cccb716 100644
--- a/calendar/gui/alarm-notify/alarm-queue.c
+++ b/calendar/gui/alarm-notify/alarm-queue.c
@@ -379,9 +379,10 @@ remove_queued_alarm (CompQueuedAlarms *cqa, gpointer alarm_id,
 /**
  * has_known_notification:
  * Test for notification method and returns if it knows it or not.
- * @param comp Component with an alarm.
- * @param alarm_uid ID of the alarm in the comp to test.
- * @return TRUE when we know the notification type, FALSE otherwise.
+ * @comp: Component with an alarm.
+ * @alarm_uid: ID of the alarm in the comp to test.
+ *
+ * Returns: %TRUE when we know the notification type, %FALSE otherwise.
  */
 static gboolean
 has_known_notification (ECalComponent *comp, const gchar *alarm_uid)
@@ -2179,8 +2180,8 @@ alarm_queue_remove_async (struct _alarm_client_msg *msg)
 /** alarm_queue_remove_client
  *
  * asynchronously remove client from alarm queue.
- * @param client Client to remove.
- * @param immediately Indicates whether use thread or do it right now.
+ * @client: Client to remove.
+ * @immediately: Indicates whether use thread or do it right now.
  */
 
 void
diff --git a/calendar/gui/comp-util.c b/calendar/gui/comp-util.c
index 7dae1826de..36f5a841e4 100644
--- a/calendar/gui/comp-util.c
+++ b/calendar/gui/comp-util.c
@@ -527,11 +527,11 @@ cal_comp_util_get_n_icons (ECalComponent *comp, GSList **pixbufs)
 
 /**
  * cal_comp_selection_set_string_list
- * Stores list of strings into selection target data.
- * Use @ref cal_comp_selection_get_string_list to get this list from target data.
+ * @data: Selection data, where to put list of strings.
+ * @str_list: List of strings. (Each element is of type const gchar *.)
  *
- * @param data Selection data, where to put list of strings.
- * @param str_list List of strings. (Each element is of type const gchar *.)
+ * Stores list of strings into selection target data.  Use
+ * cal_comp_selection_get_string_list() to get this list from target data.
  **/
 void
 cal_comp_selection_set_string_list (GtkSelectionData *data, GSList *str_list)
@@ -561,13 +561,14 @@ cal_comp_selection_set_string_list (GtkSelectionData *data, GSList *str_list)
 
 /**
  * cal_comp_selection_get_string_list
+ * @data: Selection data, where to put list of strings.
+ *
  * Converts data from selection to list of strings. Data should be assigned
- * to selection data with @ref cal_comp_selection_set_string_list.
- * Each string in newly created list should be freed by g_free.
- * List itself should be freed by g_slist_free.
+ * to selection data with cal_comp_selection_set_string_list().
+ * Each string in newly created list should be freed by g_free().
+ * List itself should be freed by g_slist_free().
  *
- * @param data Selection data, where to put list of strings.
- * @return Newly allocated GSList of strings.
+ * Returns: Newly allocated #GSList of strings.
  **/
 GSList *
 cal_comp_selection_get_string_list (GtkSelectionData *selection_data)
@@ -630,10 +631,11 @@ datetime_to_zone (ECal *client, ECalComponentDateTime *date, const gchar *tzid)
 
 /**
  * cal_comp_set_dtstart_with_oldzone:
+ * @client: ECal structure, to retrieve timezone from, when required.
+ * @comp: Component, where make the change.
+ * @pdate: Value, to change to.
+ *
  * Changes 'dtstart' of the component, but converts time to the old timezone.
- * @param client ECal structure, to retrieve timezone from, when required.
- * @param comp Component, where make the change.
- * @param pdate Value, to change to.
  **/
 void
 cal_comp_set_dtstart_with_oldzone (ECal *client, ECalComponent *comp, const ECalComponentDateTime *pdate)
@@ -655,10 +657,11 @@ cal_comp_set_dtstart_with_oldzone (ECal *client, ECalComponent *comp, const ECal
 
 /**
  * cal_comp_set_dtend_with_oldzone:
+ * @client: ECal structure, to retrieve timezone from, when required.
+ * @comp: Component, where make the change.
+ * @pdate: Value, to change to.
+ *
  * Changes 'dtend' of the component, but converts time to the old timezone.
- * @param client ECal structure, to retrieve timezone from, when required.
- * @param comp Component, where make the change.
- * @param pdate Value, to change to.
  **/
 void
 cal_comp_set_dtend_with_oldzone (ECal *client, ECalComponent *comp, const ECalComponentDateTime *pdate)
@@ -748,13 +751,15 @@ update_objects (ECal *client, icalcomponent *icalcomp)
 
 /**
  * cal_comp_process_source_list_drop:
+ * @destination: Where to put the component.
+ * @comp: Component to move/copy.
+ * @action: What to do.
+ * @source_uid: Where the component comes from; used when moving.
+ * @source_list: The ESourceList over which the event was called.
+ *
  * Processes the drop signal over the ESourceList.
- * @param destination Where to put the component.
- * @param comp Component to move/copy.
- * @param action What to do.
- * @param source_uid Where the component comes from; used when moving.
- * @param source_list The ESourceList over which the event was called.
- * @return Whether was the operation successful.
+ *
+ * Returns: Whether was the operation successful.
  **/
 gboolean
 cal_comp_process_source_list_drop (ECal *destination, icalcomponent *comp, GdkDragAction action, const gchar *source_uid, ESourceList *source_list)
diff --git a/calendar/gui/dialogs/comp-editor-util.c b/calendar/gui/dialogs/comp-editor-util.c
index a29d75739c..a98314b389 100644
--- a/calendar/gui/dialogs/comp-editor-util.c
+++ b/calendar/gui/dialogs/comp-editor-util.c
@@ -285,12 +285,18 @@ free_slist_strs (gpointer data)
 
 /**
  * comp_editor_manage_new_attendees:
+ * @comp: The component.
+ * @ma: An attendee.
+ * @add: %TRUE to add attendee's email to new-attendees, %FALSE to remove
+ * from it.
+ *
  * Manages the 'new-attendees' string of new attendees of the component.
- * @param comp: The component.
- * @param ma: An attendee.
- * @param add: TRUE to add attendee's email to new-attendees, FALSE to remove from it.
  *
- * @note The list is just string of emails separated by ';'
+ * <note>
+ *   <para>
+ *     The list is just string of emails separated by ';'
+ *   </para>
+ * </note>
  **/
 void
 comp_editor_manage_new_attendees (ECalComponent *comp,
@@ -316,9 +322,10 @@ comp_editor_manage_new_attendees (ECalComponent *comp,
 
 /**
  * comp_editor_copy_new_attendees:
- * Copies "new-attendees" information from src to des component.
- * @param des: Component, to copy to.
- * @param src: Component, to copy from.
+ * @des: Component, to copy to.
+ * @src: Component, to copy from.
+ *
+ * Copies "new-attendees" information from @src to @des component.
  **/
 void
 comp_editor_copy_new_attendees (ECalComponent *des, ECalComponent *src)
@@ -337,9 +344,10 @@ comp_editor_copy_new_attendees (ECalComponent *des, ECalComponent *src)
 
 /**
  * comp_editor_have_in_new_attendees:
- * @param comp: Component with the "new-attendees" possibly set.
- * @param ma: Meeting attendee to check.
- * @return Whether ma is present in the list of new attendees of the comp.
+ * @comp: Component with the "new-attendees" possibly set.
+ * @ma: Meeting attendee to check.
+ *
+ * Returns: Whether @ma is present in the list of new attendees of the comp.
  **/
 gboolean
 comp_editor_have_in_new_attendees (ECalComponent *comp, EMeetingAttendee *ma)
diff --git a/calendar/gui/dialogs/comp-editor.c b/calendar/gui/dialogs/comp-editor.c
index 2d0f524c10..b6be8bd7e6 100644
--- a/calendar/gui/dialogs/comp-editor.c
+++ b/calendar/gui/dialogs/comp-editor.c
@@ -3193,11 +3193,11 @@ comp_editor_get_comp (CompEditor *editor)
 
 /**
  * comp_editor_get_current_comp
+ * @editor: a #CompEditor
+ * @correct: Set this no non-%NULL if you are interested to know if all
+ * pages reported success when filling component.
  *
- * @param editor
- * @param correct Set this no non-NULL if you are interested to know if
- *                all pages reported success when filling component.
- * @return Newly allocated component, should be unref-ed by g_object_unref.
+ * Returns: Newly allocated component, should be unref-ed by g_object_unref().
  **/
 ECalComponent *
 comp_editor_get_current_comp (CompEditor *editor, gboolean *correct)
diff --git a/calendar/gui/dialogs/event-page.c b/calendar/gui/dialogs/event-page.c
index e4459a4779..5d340a7b13 100644
--- a/calendar/gui/dialogs/event-page.c
+++ b/calendar/gui/dialogs/event-page.c
@@ -3304,9 +3304,10 @@ event_page_get_name_selector (EventPage *epage)
 
 /**
  * event_page_add_attendee
+ * @epage: an #EventPage
+ * @attendee: Attendee to be added.
+ *
  * Add attendee to meeting store and name selector.
- * @param epage EventPage.
- * @param attendee Attendee to be added.
  **/
 void
 event_page_add_attendee (EventPage *epage, EMeetingAttendee *attendee)
@@ -3328,8 +3329,9 @@ event_page_add_attendee (EventPage *epage, EMeetingAttendee *attendee)
 
 /**
  * event_page_remove_all_attendees
+ * @epage: an #EventPage
+ *
  * Removes all attendees from the meeting store and name selector.
- * @param epage EventPage.
  **/
 void
 event_page_remove_all_attendees (EventPage *epage)
diff --git a/calendar/gui/dialogs/task-page.c b/calendar/gui/dialogs/task-page.c
index 8555afdcc9..2bc4988b6e 100644
--- a/calendar/gui/dialogs/task-page.c
+++ b/calendar/gui/dialogs/task-page.c
@@ -2148,9 +2148,10 @@ task_page_get_cancel_comp (TaskPage *page)
 
 /**
  * task_page_add_attendee
+ * @tpage: a #TaskPage
+ * @attendee: Attendee to be added.
+ *
  * Add attendee to meeting store and name selector.
- * @param tpage TaskPage.
- * @param attendee Attendee to be added.
  **/
 void
 task_page_add_attendee (TaskPage *tpage, EMeetingAttendee *attendee)
diff --git a/calendar/gui/e-cal-model-tasks.c b/calendar/gui/e-cal-model-tasks.c
index c4690e3fca..55548f489c 100644
--- a/calendar/gui/e-cal-model-tasks.c
+++ b/calendar/gui/e-cal-model-tasks.c
@@ -1179,10 +1179,10 @@ e_cal_model_tasks_set_color_overdue (ECalModelTasks *model,
 
 /**
  * e_cal_model_tasks_mark_comp_complete
- * Marks component as complete and commits changes to the calendar backend.
+ * @model: Currently not used...
+ * @comp_data: Component of our interest
  *
- * @param model Currently not used...
- * @param comp_data Component of our interest
+ * Marks component as complete and commits changes to the calendar backend.
  **/
 void e_cal_model_tasks_mark_comp_complete (ECalModelTasks *model, ECalModelComponent *comp_data)
 {
@@ -1201,10 +1201,10 @@ void e_cal_model_tasks_mark_comp_complete (ECalModelTasks *model, ECalModelCompo
 
 /**
  * e_cal_model_tasks_mark_comp_incomplete
- * Marks component as incomplete and commits changes to the calendar backend.
+ * @model: Currently not used...
+ * @comp_data: Component of our interest
  *
- * @param model Currently not used...
- * @param comp_data Component of our interest
+ * Marks component as incomplete and commits changes to the calendar backend.
  **/
 void e_cal_model_tasks_mark_comp_incomplete (ECalModelTasks *model, ECalModelComponent *comp_data)
 {
@@ -1244,9 +1244,9 @@ void e_cal_model_tasks_mark_comp_incomplete (ECalModelTasks *model, ECalModelCom
 
 /**
  * commit_component_changes
- * Commits changes to the backend calendar of the component.
+ * @comp_data: Component of our interest, which has been changed.
  *
- * @param comp_data Component of our interest, which has been changed.
+ * Commits changes to the backend calendar of the component.
  **/
 static void
 commit_component_changes (ECalModelComponent *comp_data)
diff --git a/calendar/gui/e-cal-model.c b/calendar/gui/e-cal-model.c
index c9f92b626d..26d88898e1 100644
--- a/calendar/gui/e-cal-model.c
+++ b/calendar/gui/e-cal-model.c
@@ -1234,11 +1234,14 @@ ecm_set_value_at (ETableModel *etm, gint col, gint row, gconstpointer value)
 
 /**
  * e_cal_model_test_row_editable
- * Checks if component at row 'row' is editable or not. It doesn't check bounds for 'row'.
+ * @model: an #ECalModel
+ * @row: Row of our interest. -1 is editable only when default client is
+ * editable.
  *
- * @param model Calendar model.
- * @param row Row of our interest. -1 is editable only when default client is editable.
- * @return Whether row is editable or not.
+ * Checks if component at @row is editable or not.  It doesn't check bounds
+ * for @row.
+ *
+ * Returns: Whether @row is editable or not.
  **/
 gboolean
 e_cal_model_test_row_editable (ECalModel *model, gint row)
diff --git a/calendar/gui/e-calendar-view.c b/calendar/gui/e-calendar-view.c
index 60371ae036..7a8a4ea6bf 100644
--- a/calendar/gui/e-calendar-view.c
+++ b/calendar/gui/e-calendar-view.c
@@ -1497,10 +1497,11 @@ e_calendar_view_new_appointment_for (ECalendarView *cal_view,
 
 /**
  * e_calendar_view_new_appointment_full
- * @param cal_view: A calendar view.
- * @param all_day: Whether create all day event or not.
- * @param meeting: This is a meeting or an appointment.
- * @param no_past_date: Don't create event in past date, use actual date instead (if TRUE).
+ * @cal_view: an #ECalendarView
+ * @all_day: Whether create all day event or not.
+ * @meeting: This is a meeting or an appointment.
+ * @no_past_date: Don't create event in past date, use actual date instead
+ * (if %TRUE).
  *
  * Opens an event editor dialog for a new appointment. The appointment's
  * start and end times are set to the currently selected time range in
diff --git a/calendar/gui/ea-calendar-helpers.c b/calendar/gui/ea-calendar-helpers.c
index b9c6c2415f..74d0d7307b 100644
--- a/calendar/gui/ea-calendar-helpers.c
+++ b/calendar/gui/ea-calendar-helpers.c
@@ -33,8 +33,8 @@
 /**
  * ea_calendar_helpers_get_accessible_for
  * @canvas_item: the canvas item for a event or a jump button
- * @returns: the atk object for the canvas_item
  *
+ * Returns: the atk object for the canvas_item
  **/
 AtkObject *
 ea_calendar_helpers_get_accessible_for (GnomeCanvasItem *canvas_item)
@@ -67,10 +67,10 @@ ea_calendar_helpers_get_accessible_for (GnomeCanvasItem *canvas_item)
 /**
  * ea_calendar_helpers_get_view_widget_from:
  * @canvas_item: the canvas item for a event or a jump button
- * @returns: the cal view widget if exists
  *
  * Get the cal view widget contains the canvas_item.
  *
+ * Returns: the cal view widget if exists
  **/
 ECalendarView *
 ea_calendar_helpers_get_cal_view_from (GnomeCanvasItem *canvas_item)
@@ -96,10 +96,10 @@ ea_calendar_helpers_get_cal_view_from (GnomeCanvasItem *canvas_item)
 /**
  * ea_calendar_helpers_get_cal_view_event_from
  * @canvas_item: the cavas_item (e_text) for the event
- * @returns: the ECalendarViewEvent
  *
  * Get the ECalendarViewEvent for the canvas_item.
  *
+ * Returns: the ECalendarViewEvent
  **/
 ECalendarViewEvent *
 ea_calendar_helpers_get_cal_view_event_from (GnomeCanvasItem *canvas_item)
diff --git a/calendar/gui/gnome-cal.c b/calendar/gui/gnome-cal.c
index 3e478a063a..e07e9f2545 100644
--- a/calendar/gui/gnome-cal.c
+++ b/calendar/gui/gnome-cal.c
@@ -1983,8 +1983,8 @@ gnome_calendar_set_selected_time_range (GnomeCalendar *gcal,
 /**
  * gnome_calendar_new_task:
  * @gcal: An Evolution calendar.
- * @param dtstart Start time of the task, in same timezone as model.
- * @param dtend End time of the task, in same timezone as model.
+ * @dtstart: Start time of the task, in same timezone as model.
+ * @dtend: End time of the task, in same timezone as model.
  *
  * Opens a task editor dialog for a new task. dtstart or dtend can be NULL.
  **/
diff --git a/plugins/pst-import/pst-importer.c b/plugins/pst-import/pst-importer.c
index c9449695ca..afd4767d5c 100644
--- a/plugins/pst-import/pst-importer.c
+++ b/plugins/pst-import/pst-importer.c
@@ -206,8 +206,6 @@ folder_selected (EMFolderSelectionButton *button, EImportTargetURI *target)
 
 /**
  * Suggest a folder to import data into
- * @param target
- * @return
  */
 static gchar *
 get_suggested_foldername (EImportTargetURI *target)
@@ -639,11 +637,13 @@ pst_process_item (PstImporter *m, pst_desc_tree *d_ptr)
 }
 
 /**
- * Convert string to utf8. Currently we just use the locale, but maybe there is encoding
- * information hidden somewhere in the PST file?
+ * string_to_utf8:
+ * @string: String from PST file
  *
- * @param string String from PST file
- * @return utf8 representation (caller should free), or NULL for error.
+ * Convert string to utf8. Currently we just use the locale, but maybe
+ * there is encoding information hidden somewhere in the PST file?
+ *
+ * Returns: utf8 representation (caller should free), or NULL for error.
  */
 gchar *
 string_to_utf8 (const gchar *string)
@@ -659,9 +659,12 @@ string_to_utf8 (const gchar *string)
 }
 
 /**
+ * foldername_to_utf8:
+ * @foldername: from PST file
+ *
  * Convert foldername to utf8 and escape characters if needed
- * @param foldername from PST file
- * @return converted folder name, or NULL for error. Caller should free
+ *
+ * Returns: converted folder name, or NULL for error. Caller should free
  */
 gchar *
 foldername_to_utf8 (const gchar *pstname)
@@ -712,8 +715,11 @@ pst_process_folder (PstImporter *m, pst_item *item)
 }
 
 /**
- * Create current folder in mail hierarchy. Parent folders will also be created.
- * @param m PstImporter set to current folder
+ * pst_create_folder:
+ * @m: PstImporter set to current folder
+ *
+ * Create current folder in mail hierarchy. Parent folders will also be
+ * created.
  */
 static void
 pst_create_folder (PstImporter *m)
@@ -777,9 +783,13 @@ pst_create_folder (PstImporter *m)
 }
 
 /**
- * Create a camel mime part from given PST attachment
- * @param attach attachment to convert
- * @return CamelMimePart containing data and mime type
+ * attachment_to_part:
+ * @m: a #PstImporter
+ * @attach: attachment to convert
+ *
+ * Create a #CamelMimePart from given PST attachment
+ *
+ * Returns: #CamelMimePart containing data and mime type
  */
 static CamelMimePart *
 attachment_to_part (PstImporter *m, pst_item_attach *attach)
@@ -1213,10 +1223,13 @@ pst_process_contact (PstImporter *m, pst_item *item)
 }
 
 /**
+ * get_ical_date:
+ * @date: time value from libpst
+ * @is_date: treat as date only (all day event)?
+ *
  * Convert pst time to icaltimetype
- * @param date time value from libpst
- * @param is_date treat as date only (all day event)?
- * @return converted date
+ *
+ * Returns: converted date
  */
 struct icaltimetype
 get_ical_date (FILETIME *date, gboolean is_date)
@@ -1682,10 +1695,13 @@ e_plugin_lib_enable (EPlugin *ep, gint enable)
 }
 
 /**
+ * pst_init:
+ * @pst: pst_file structure to be used by libpst
+ * @filename: path to file
+ *
  * Open PST file and determine root folder name
- * @param pst: pst_file structure to be used by libpst
- * @param filename : path to file
- * @return 0 for sucess, -1 for failure
+ *
+ * Returns: 0 for sucess, -1 for failure
  */
 gint
 pst_init (pst_file *pst, gchar *filename)
@@ -1717,10 +1733,15 @@ pst_init (pst_file *pst, gchar *filename)
 }
 
 /**
+ * get_pst_rootname:
+ * @pst: pst_file structure to be used by libpst
+ * @filename: if non %NULL, fallback to this name if folder name is not
+ * available
+ *
  * Open determine root folder name of PST file
- * @param pst: pst_file structure to be used by libpst
- * @param filename : if non NULL, fallback to this name if folder name is not available
- * @return pointer to name of root folder (should be freed by caller), or NULL if error
+ *
+ * Returns: pointer to name of root folder (should be freed by caller),
+ * or %NULL if error
  */
 gchar *
 get_pst_rootname (pst_file *pst, gchar *filename)
diff --git a/widgets/misc/e-dateedit.c b/widgets/misc/e-dateedit.c
index 9aff9de005..b57849c131 100644
--- a/widgets/misc/e-dateedit.c
+++ b/widgets/misc/e-dateedit.c
@@ -2205,10 +2205,12 @@ e_date_edit_time_is_valid	(EDateEdit	*dedit)
 
 /**
  * e_date_edit_have_time
- * Check if time is set, i.e. it isn't 'None'/empty. Date can be set in this case.
+ * @dedit: an #EDateEdit
  *
- * @param dedit an EDateEdit widget.
- * @return TRUE is time is set, FALSE otherwise.
+ * Check if time is set, i.e. it isn't 'None'/empty. Date can be set in
+ * this case.
+ *
+ * Returns: %TRUE is time is set, %FALSE otherwise.
  **/
 gboolean
 e_date_edit_have_time (EDateEdit *dedit)
diff --git a/widgets/table/e-table-sorting-utils.c b/widgets/table/e-table-sorting-utils.c
index 2fa679644a..1fa91214c2 100644
--- a/widgets/table/e-table-sorting-utils.c
+++ b/widgets/table/e-table-sorting-utils.c
@@ -376,11 +376,13 @@ e_table_sorting_utils_tree_insert (ETreeModel *source, ETableSortInfo *sort_info
 /**
  * e_table_sorting_utils_create_cmp_cache:
  *
- * Creates a new compare cache, which is storing pairs of string keys and string values.
- * This can be accessed by @ref e_table_sorting_utils_lookup_cmp_cache and
- * @ref e_table_sorting_utils_add_to_cmp_cache.
+ * Creates a new compare cache, which is storing pairs of string keys and
+ * string values.  This can be accessed by
+ * e_table_sorting_utils_lookup_cmp_cache() and
+ * e_table_sorting_utils_add_to_cmp_cache().
  *
- * Returned pointer should be freed with @ref e_table_sorting_utils_free_cmp_cache.
+ * Returned pointer should be freed with
+ * e_table_sorting_utils_free_cmp_cache().
  **/
 gpointer
 e_table_sorting_utils_create_cmp_cache (void)
@@ -392,8 +394,8 @@ e_table_sorting_utils_create_cmp_cache (void)
  * e_table_sorting_utils_free_cmp_cache:
  * @cmp_cache: a compare cache; cannot be %NULL
  *
- * Frees a compare cache previously created
- * with @ref e_table_sorting_utils_create_cmp_cache.
+ * Frees a compare cache previously created with
+ * e_table_sorting_utils_create_cmp_cache().
  **/
 void
 e_table_sorting_utils_free_cmp_cache (gpointer cmp_cache)