From ab870b27cd05cc39e4755de9c6d9e02944977c17 Mon Sep 17 00:00:00 2001 From: Matthew Barnes Date: Tue, 1 Mar 2011 13:04:09 -0500 Subject: Fix Gtk-Doc comment notation. Seeing lots of what I assume to be doxygen syntax in comment blocks. --- calendar/gui/alarm-notify/alarm-queue.c | 11 +++--- calendar/gui/comp-util.c | 47 +++++++++++++----------- calendar/gui/dialogs/comp-editor-util.c | 28 +++++++++----- calendar/gui/dialogs/comp-editor.c | 8 ++-- calendar/gui/dialogs/event-page.c | 8 ++-- calendar/gui/dialogs/task-page.c | 5 ++- calendar/gui/e-cal-model-tasks.c | 16 ++++---- calendar/gui/e-cal-model.c | 11 ++++-- calendar/gui/e-calendar-view.c | 9 +++-- calendar/gui/ea-calendar-helpers.c | 6 +-- calendar/gui/gnome-cal.c | 4 +- plugins/pst-import/pst-importer.c | 65 ++++++++++++++++++++++----------- widgets/misc/e-dateedit.c | 8 ++-- widgets/table/e-table-sorting-utils.c | 14 ++++--- 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 ';' + * + * + * The list is just string of emails separated by ';' + * + * **/ 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) -- cgit v1.2.3