Fix Gtk-Doc comment notation.

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

11 files changed, 87 insertions, 66 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.
  **/