project: document classes

.gitignore

@@ -96,4 +96,4 @@ gtk-doc.make
 doc/reference/xml
 doc/reference/html
 doc/reference/*.stamp
-doc/reference/*.xml
+doc/reference/version.xml

doc/reference/Makefile.am

@@ -34,6 +34,7 @@ if ENABLE_DOC_CROSS_REFERENCES
 # Extra options to supply to gtkdoc-fixref. Not normally needed.
 # e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
 FIXXREF_OPTIONS = \
+        --extra-dir=$(GTK_PREFIX)/share/gtk-doc/html/evolution-data-server \
 	--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/glib       \
 	--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/gobject    \
 	--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/gio        \
@@ -55,7 +56,13 @@ CFILE_GLOB = \
 IGNORE_HFILES = $(NULL)
 
 # Images to copy into HTML directory.
-HTML_IMAGES = $(NULL)
+HTML_IMAGES =                                                    \
+        images/gcal-edit-dialog.png                              \
+        images/gcal-event-widget.png                             \
+        images/gcal-source-dialog.png                            \
+        images/gcal-window.png                                   \
+        images/gcal-window_agendas.png                           \
+        $(NULL)
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml

doc/reference/gnome-calendar-decl-list.txt

@@ -152,9 +152,7 @@ GcalEditDialog
 <SECTION>
 <FILE>gcal-enum-types</FILE>
 <SUBSECTION Standard>
-GCAL_EDITABLE_PROPERTY
 GCAL_WINDOW_VIEW_TYPE
-event_editable_property_get_type
 gcal_window_view_type_get_type
 </SECTION>
 
@@ -448,8 +446,6 @@ MINUTES_PER_DAY
 MAX_MINUTES
 gcal_clear_datetime
 GcalWindowViewType
-EventEditableProperty
-GcalTranslateFunc
 icaltime_get_type
 datetime_compare_date
 datetime_to_icaltime
@@ -488,8 +484,6 @@ GCAL_TYPE_VIEW
 GcalViewInterface
 gcal_view_set_date
 gcal_view_get_date
-gcal_view_get_initial_date
-gcal_view_get_final_date
 gcal_view_clear_marks
 gcal_view_get_children_by_uuid
 GcalView

doc/reference/gnome-calendar-decl.txt

@@ -764,10 +764,6 @@ struct _GcalViewInterface
                                                         icaltimetype *start_span,
                                                         icaltimetype *end_span);
 
-  /* Time handling related API */
-  icaltimetype*  (*get_initial_date)                   (GcalView    *view);
-  icaltimetype*  (*get_final_date)                     (GcalView    *view);
-
   /* Marks related API */
   void           (*clear_marks)                        (GcalView    *view);
 
@@ -786,16 +782,6 @@ GcalView     *view, icaltimetype *date
 GcalView     *view
 </FUNCTION>
 <FUNCTION>
-<NAME>gcal_view_get_initial_date</NAME>
-<RETURNS>icaltimetype * </RETURNS>
-GcalView     *view
-</FUNCTION>
-<FUNCTION>
-<NAME>gcal_view_get_final_date</NAME>
-<RETURNS>icaltimetype * </RETURNS>
-GcalView     *view
-</FUNCTION>
-<FUNCTION>
 <NAME>gcal_view_clear_marks</NAME>
 <RETURNS>void           </RETURNS>
 GcalView     *view
@@ -1023,15 +1009,6 @@ ECalDataModel *data_model
 <RETURNS>GType  </RETURNS>
 void
 </FUNCTION>
-<MACRO>
-<NAME>GCAL_EDITABLE_PROPERTY</NAME>
-#define GCAL_EDITABLE_PROPERTY	(event_editable_property_get_type())
-</MACRO>
-<FUNCTION>
-<NAME>event_editable_property_get_type</NAME>
-<RETURNS>GType  </RETURNS>
-void
-</FUNCTION>
 <FUNCTION>
 <NAME>gcal_log_init</NAME>
 <RETURNS>void                  </RETURNS>
@@ -1069,23 +1046,6 @@ typedef enum
   GCAL_WINDOW_VIEW_SEARCH,
 } GcalWindowViewType;
 </ENUM>
-<ENUM>
-<NAME>EventEditableProperty</NAME>
-typedef enum
-{
-  EVENT_SUMMARY = 0,
-  EVENT_START_DATE,
-  EVENT_END_DATE,
-  EVENT_LOCATION,
-  EVENT_DESCRIPTION,
-  EVENT_SOURCE,
-} EventEditableProperty;
-</ENUM>
-<USER_FUNCTION>
-<NAME>GcalTranslateFunc</NAME>
-<RETURNS>const gchar *</RETURNS>
-GtkWidget             *source_widget
-</USER_FUNCTION>
 <FUNCTION>
 <NAME>icaltime_get_type</NAME>
 <RETURNS>GType            </RETURNS>

doc/reference/gnome-calendar-undeclared.txt

@@ -0,0 +1,4 @@
+EventEditableProperty
+GcalTranslateFunc
+gcal_view_get_final_date
+gcal_view_get_initial_date

doc/reference/gnome-calendar-undocumented.txt

@@ -1,7 +1,7 @@
-47% symbol docs coverage.
+60% symbol docs coverage.
-264 symbols documented.
+324 symbols documented.
-182 symbols incomplete.
+108 symbols incomplete.
-296 not documented.
+216 not documented.
 
 
 ALIGNED (<parameters>)
@@ -12,22 +12,14 @@ ECalDataModel:timezone
 ECalDataModelForeachFunc (<parameters>)
 ECalDataModelViewState (<items>)
 EThreadJobFunc (<parameters>)
-EventEditableProperty (<items>)
+EventEditableProperty
-GCAL_BUG (<parameters>)
 GCAL_ENABLE_TRACE
-GCAL_ENTRY
 GCAL_EVENT_ERROR
-GCAL_EXIT
-GCAL_GOTO (<parameters>)
 GCAL_LOG_LEVEL_TRACE
-GCAL_PROBE
 GCAL_RESPONSE_CREATE_EVENT
 GCAL_RESPONSE_DELETE_EVENT
 GCAL_RESPONSE_REMOVE_SOURCE
 GCAL_RESPONSE_SAVE_EVENT
-GCAL_RETURN (<parameters>)
-GCAL_TODO (<parameters>)
-GCAL_TRACE_MSG (<parameters>)
 GCAL_TYPE_APPLICATION
 GCAL_TYPE_DATE_CHOOSER
 GCAL_TYPE_DATE_CHOOSER_DAY
@@ -60,7 +52,6 @@ GcalDateChooserDayOptionsCallback (<parameters>)
 GcalDateSelector
 GcalEditDialog
 GcalEvent
-GcalEventError (<items>)
 GcalEventWidget
 GcalEventWidget::activate
 GcalManager
@@ -74,16 +65,14 @@ GcalMultiChoice
 GcalMultiChoice::wrapped
 GcalMultiChoiceFormatCallback (<parameters>)
 GcalQuickAddPopover
-GcalRangeTraverseFunc (<parameters>)
 GcalSearchView
 GcalShellSearchProvider
 GcalShellSearchProviderClass (<items>)
 GcalSourceDialog
-GcalSourceDialogMode (<items>)
 GcalSubscriberView::event-activated
 GcalSubscriberViewPrivate (<items>)
 GcalTimeSelector
-GcalTranslateFunc (<parameters>)
+GcalTranslateFunc
 GcalView
 GcalViewInterface (<items>)
 GcalWeekGrid
@@ -93,29 +82,19 @@ GcalWeekHeader::event-activated
 GcalWeekView
 GcalWeekView::event-activated
 GcalWindow
-GcalWindowViewType (<items>)
 GcalYearView
 GcalYearView::event-activated
 ICAL_TIME_TYPE
 MAX_MINUTES
 MINUTES_PER_DAY
-action_widget_activated (Returns)
+_GCAL_BUG
-back_button_clicked (Returns)
 build_component_from_details (summary, initial_date, final_date)
-calendar_file_selected (Returns)
 calendar_get_resource
-calendar_listbox_row_activated (Returns)
-clear_pages (Returns)
-datetime_compare_date (<parameters>)
-datetime_is_date (<parameters>)
-datetime_to_icaltime (<parameters>)
-description_label_link_activated (Returns)
 e_cal_data_model_remove_client (data_model)
 e_cal_data_model_subscriber_component_added (comp)
-e_strftime_fix_am_pm (<parameters>)
+e_strftime_fix_am_pm (str, tm, fmt, max)
-e_utf8_strftime_fix_am_pm (<parameters>)
+e_utf8_strftime_fix_am_pm (fmt, max, str, tm)
 fix_popover_menu_icons (popover)
-format_utc_offset (<parameters>)
 free_row_data (Returns)
 gcal_application_get_manager (<parameters>)
 gcal_application_get_settings (<parameters>)
@@ -143,15 +122,6 @@ gcal_date_chooser_set_show_day_names (<parameters>)
 gcal_date_chooser_set_show_heading (<parameters>)
 gcal_date_chooser_set_show_week_numbers (<parameters>)
 gcal_date_selector_new
-gcal_dup_icaltime (<parameters>)
-gcal_edit_dialog_get_date_end (<parameters>)
-gcal_edit_dialog_get_date_start (<parameters>)
-gcal_edit_dialog_get_event (<parameters>)
-gcal_edit_dialog_new
-gcal_edit_dialog_set_event (<parameters>)
-gcal_edit_dialog_set_event_is_new (<parameters>)
-gcal_edit_dialog_set_manager (<parameters>)
-gcal_edit_dialog_set_time_format (<parameters>)
 gcal_event_get_description (self)
 gcal_event_set_summary (self)
 gcal_event_widget_clone (<parameters>)
@@ -163,37 +133,18 @@ gcal_event_widget_new (<parameters>)
 gcal_event_widget_set_date_start (date_start)
 gcal_event_widget_set_has_reminders (<parameters>)
 gcal_event_widget_set_read_only (<parameters>)
-gcal_get_month_name (<parameters>)
-gcal_get_pixbuf_from_color (color, size)
-gcal_get_surface_from_color (<parameters>)
-gcal_get_weekday (<parameters>)
 gcal_log_init
-gcal_manager_add_source (name, backend)
+gcal_manager_add_source (backend, name)
-gcal_manager_create_event (<parameters>)
 gcal_manager_get_default_source
-gcal_manager_get_event_from_shell_search (<parameters>)
+gcal_manager_get_events (range_end, range_start)
-gcal_manager_get_events (manager, range_end, range_start)
+gcal_manager_get_goa_client (manager)
-gcal_manager_get_goa_client (<parameters>)
+gcal_manager_get_shell_search_events (manager)
-gcal_manager_get_loading (<parameters>)
+gcal_manager_query_client_data (field, source, manager)
-gcal_manager_get_shell_search_events (<parameters>)
+gcal_manager_set_search_subscriber (manager)
-gcal_manager_get_source (manager)
+gcal_manager_set_shell_search_subscriber (manager)
-gcal_manager_get_sources (manager)
+gcal_manager_set_subscriber (manager)
-gcal_manager_get_sources_connected (manager)
+gcal_manager_setup_shell_search (self)
-gcal_manager_get_system_timezone (<parameters>)
+gcal_manager_shell_search_done (manager)
-gcal_manager_is_client_writable (<parameters>)
-gcal_manager_move_event_to_source (<parameters>)
-gcal_manager_new_with_settings
-gcal_manager_query_client_data (source, manager, field)
-gcal_manager_refresh (<parameters>)
-gcal_manager_remove_event (<parameters>)
-gcal_manager_set_default_source
-gcal_manager_set_search_subscriber (<parameters>)
-gcal_manager_set_shell_search_subscriber (<parameters>)
-gcal_manager_set_subscriber (<parameters>)
-gcal_manager_setup_shell_search (<parameters>)
-gcal_manager_shell_search_done (<parameters>)
-gcal_manager_update_event (<parameters>)
-gcal_month_view_get_final_date
 gcal_month_view_motion_notify_event (widget, event, Returns)
 gcal_month_view_set_first_weekday (self)
 gcal_month_view_set_manager (<parameters>)
@@ -204,7 +155,6 @@ gcal_multi_choice_set_choices (<parameters>)
 gcal_multi_choice_set_format_callback (<parameters>)
 gcal_multi_choice_set_value (<parameters>)
 gcal_quick_add_popover_new
-gcal_range_tree_count_entries_at_range (<parameters>)
 gcal_search_view_new
 gcal_search_view_search (<parameters>)
 gcal_search_view_set_search
@@ -213,15 +163,14 @@ gcal_shell_search_provider_dbus_export (<parameters>)
 gcal_shell_search_provider_dbus_unexport (<parameters>)
 gcal_shell_search_provider_new
 gcal_source_dialog_new
-gcal_source_dialog_set_manager (Returns)
-gcal_source_dialog_set_mode (Returns)
-gcal_source_dialog_set_source (Returns)
 gcal_subscriber_view_get_child_by_uuid (<parameters>)
 gcal_time_selector_get_time (<parameters>)
 gcal_time_selector_new
 gcal_time_selector_set_time (<parameters>)
 gcal_time_selector_set_time_format (<parameters>)
 gcal_view_get_date (<parameters>)
+gcal_view_get_final_date
+gcal_view_get_initial_date
 gcal_view_set_date (<parameters>)
 gcal_week_grid_add_event (<parameters>)
 gcal_week_grid_clear_marks (<parameters>)
@@ -238,49 +187,21 @@ gcal_week_header_remove_event (<parameters>)
 gcal_week_header_set_first_weekday (<parameters>)
 gcal_week_header_set_manager (<parameters>)
 gcal_week_header_set_use_24h_format (<parameters>)
-gcal_week_view_get_final_date
-gcal_week_view_get_initial_date
 gcal_week_view_set_first_weekday (view, day_nr)
 gcal_week_view_set_manager (<parameters>)
 gcal_week_view_set_use_24h_format (view, use_24h)
-gcal_window_new_event (<parameters>)
-gcal_window_new_with_view_and_date (<parameters>)
-gcal_window_open_event_by_uuid (<parameters>)
-gcal_window_set_search_mode (<parameters>)
-gcal_window_set_search_query (<parameters>)
 gcal_year_view_set_current_date (<parameters>)
 gcal_year_view_set_first_weekday (<parameters>)
 gcal_year_view_set_manager (<parameters>)
 gcal_year_view_set_use_24h_format (<parameters>)
-get_alarm_trigger_minutes (<parameters>)
-get_circle_surface_from_color (<parameters>)
-get_color_name_from_source (<parameters>)
-get_desc_from_component (component)
-get_end_of_week (<parameters>)
-get_source_parent_name_color (<parameters>)
-get_start_of_week (<parameters>)
 hide_notification (Returns)
-icaltime_compare_date (date1, date2)
-icaltime_compare_with_current (<parameters>)
 icaltime_get_type
-icaltime_to_datetime (<parameters>)
-is_clock_format_24h
-is_source_enabled (<parameters>)
-name_entry_text_changed (Returns)
 notification_child_revealed_changed (Returns)
-on_local_activated (Returns)
-on_web_activated (Returns)
-online_accounts_listbox_row_activated (Returns)
-online_accounts_settings_button_clicked (Returns)
 open_event (Returns)
 remove_button_clicked (Returns)
 remove_source (Returns)
-response_signal (Returns)
-should_change_date_for_scroll (<parameters>)
 undo_remove_action (Returns)
 update_view (Returns)
-uri_get_fields (uri, schema, host, path)
-url_entry_text_changed (Returns)
 view_changed (object, pspec, user_data)
 
 css-code:Long_Description
@@ -297,28 +218,18 @@ gcal-date-chooser:Long_Description
 gcal-date-chooser:Short_Description
 gcal-date-selector:Long_Description
 gcal-date-selector:Short_Description
-gcal-debug:Long_Description
-gcal-debug:Short_Description
-gcal-edit-dialog:Long_Description
-gcal-edit-dialog:Short_Description
 gcal-enum-types:Long_Description
 gcal-enum-types:Short_Description
 gcal-event-widget:Long_Description
 gcal-event-widget:Short_Description
-gcal-event:Long_Description
-gcal-event:Short_Description
 gcal-log:Long_Description
 gcal-log:Short_Description
-gcal-manager:Long_Description
-gcal-manager:Short_Description
 gcal-month-view:Long_Description
 gcal-month-view:Short_Description
 gcal-multi-choice:Long_Description
 gcal-multi-choice:Short_Description
 gcal-quick-add-popover:Long_Description
 gcal-quick-add-popover:Short_Description
-gcal-range-tree:Long_Description
-gcal-range-tree:Short_Description
 gcal-resources:Long_Description
 gcal-resources:Short_Description
 gcal-search-view:Long_Description
@@ -327,8 +238,6 @@ gcal-shell-search-provider-generated:Long_Description
 gcal-shell-search-provider-generated:Short_Description
 gcal-shell-search-provider:Long_Description
 gcal-shell-search-provider:Short_Description
-gcal-source-dialog:Long_Description
-gcal-source-dialog:Short_Description
 gcal-subscriber-view-private:Long_Description
 gcal-subscriber-view-private:Short_Description
 gcal-subscriber-view:Long_Description
@@ -336,7 +245,6 @@ gcal-subscriber-view:Short_Description
 gcal-time-selector:Long_Description
 gcal-time-selector:Short_Description
 gcal-utils:Long_Description
-gcal-utils:Short_Description
 gcal-view:Long_Description
 gcal-view:Short_Description
 gcal-week-grid:Long_Description
@@ -345,7 +253,5 @@ gcal-week-header:Long_Description
 gcal-week-header:Short_Description
 gcal-week-view:Long_Description
 gcal-week-view:Short_Description
-gcal-window:Long_Description
-gcal-window:Short_Description
 gcal-year-view:Long_Description
 gcal-year-view:Short_Description

doc/reference/gnome-calendar-unused.txt

@@ -4,6 +4,14 @@ fix_popover_menu_icons(window)
 gcal_event_set_summary(event)
 gcal_event_widget_set_date_start(date_end)
 gcal_manager_add_source(base_uri, relative_uri)
+gcal_manager_get_events(start_date, end_date)
+gcal_manager_get_goa_client(self)
+gcal_manager_get_shell_search_events(self)
+gcal_manager_set_search_subscriber(self)
+gcal_manager_set_shell_search_subscriber(self)
+gcal_manager_set_subscriber(self)
+gcal_manager_setup_shell_search(manager)
+gcal_manager_shell_search_done(self)
 gcal_month_view_set_first_weekday(view)
 gcal_month_view_set_use_24h_format(view)
 gcal_week_view_set_first_weekday(view)

doc/reference/gnome-calendar.hierarchy

@@ -104,8 +104,28 @@ GInterface
   GConverter
   GProxyResolver
   AtkImage
+GBoxed
+  GValueArray
+  GcalRangeTree
+  icaltimetype
+  GError
+  GVariantDict
+  GdkRectangle
+  CairoRectangleInt
+  CairoContext
+  GdkEvent
+  GtkSelectionData
+  GtkRequisition
+  GtkBorder
+  GdkColor
+  GDateTime
+  PangoAttrList
+  PangoTabArray
+  GdkRGBA
+  GTimeZone
+  GStrv
+  GDBusInterfaceInfo
 GEnum
-  EventEditableProperty
   GcalWindowViewType
   GtkAlign
   GtkStateType
@@ -133,24 +153,3 @@ GEnum
   GBusType
   GtkReliefStyle
   GtkArrowType
-GBoxed
-  GValueArray
-  GcalRangeTree
-  icaltimetype
-  GError
-  GVariantDict
-  GdkRectangle
-  CairoRectangleInt
-  CairoContext
-  GdkEvent
-  GtkSelectionData
-  GtkRequisition
-  GtkBorder
-  GdkColor
-  GDateTime
-  PangoAttrList
-  PangoTabArray
-  GdkRGBA
-  GTimeZone
-  GStrv
-  GDBusInterfaceInfo

doc/reference/gnome-calendar.types

@@ -1,6 +1,5 @@
 e_cal_data_model_get_type
 e_cal_data_model_subscriber_get_type
-event_editable_property_get_type
 gcal_application_get_type
 gcal_date_chooser_day_get_type
 gcal_date_chooser_get_type

src/gcal-debug.h.in

@@ -21,6 +21,18 @@
 
 #include <glib.h>
 
+/**
+ * SECTION:gcal-debug
+ * @short_description: Debugging macros
+ * @title:Debugging
+ * @stability:stable
+ *
+ * Macros used for tracing and debugging code. These
+ * are only valid when Calendar is compiled with tracing
+ * suppoer (pass `--enable-tracing` to the configure
+ * script to do that).
+ */
+
 G_BEGIN_DECLS
 
 #ifndef GCAL_ENABLE_TRACE
@@ -38,46 +50,158 @@ G_BEGIN_DECLS
 #endif
 
 #ifdef GCAL_ENABLE_TRACE
+
+/**
+ * GCAL_TRACE_MSG:
+ * @fmt: printf-like format of the message
+ * @...: arguments for @fmt
+ *
+ * Prints a trace message.
+ */
 # define GCAL_TRACE_MSG(fmt, ...)                                        \
    g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, "  MSG: %s():%d: " fmt,     \
          G_STRFUNC, __LINE__, ##__VA_ARGS__)
+
+/**
+ * GCAL_PROBE:
+ *
+ * Prints a probing message. Put this macro in the code when
+ * you want to check the program reaches a certain section
+ * of code.
+ */
 # define GCAL_PROBE                                                      \
    g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, "PROBE: %s():%d",           \
          G_STRFUNC, __LINE__)
+
+/**
+ * GCAL_TODO:
+ * @_msg: the message to print
+ *
+ * Prints a TODO message.
+ */
 # define GCAL_TODO(_msg)                                                 \
    g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, " TODO: %s():%d: %s",       \
          G_STRFUNC, __LINE__, _msg)
+
+/**
+ * GCAL_ENTRY:
+ *
+ * Prints an entry message. This shouldn't be used in
+ * critical functions. Place this at the beggining of
+ * the function, before any assertion.
+ */
 # define GCAL_ENTRY                                                      \
    g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, "ENTRY: %s():%d",           \
          G_STRFUNC, __LINE__)
+
+/**
+ * GCAL_EXIT:
+ *
+ * Prints an exit message. This shouldn't be used in
+ * critical functions. Place this at the end of
+ * the function, after any relevant code. If the
+ * function returns something, use GCAL_RETURN()
+ * instead.
+ */
 # define GCAL_EXIT                                                       \
    G_STMT_START {                                                        \
       g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, " EXIT: %s():%d",        \
             G_STRFUNC, __LINE__);                                        \
       return;                                                            \
    } G_STMT_END
+
+/**
+ * GCAL_GOTO:
+ * @_l: goto tag
+ *
+ * Logs a goto jump.
+ */
 # define GCAL_GOTO(_l)                                                   \
    G_STMT_START {                                                        \
       g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, " GOTO: %s():%d ("#_l")",\
             G_STRFUNC, __LINE__);                                        \
       goto _l;                                                           \
    } G_STMT_END
+
+/**
+ * GCAL_RETURN:
+ * @_r: the return value.
+ *
+ * Prints an exit message, and returns @_r. See #GCAL_EXIT.
+ */
 # define GCAL_RETURN(_r)                                                 \
    G_STMT_START {                                                        \
       g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, " EXIT: %s():%d ",       \
             G_STRFUNC, __LINE__);                                        \
       return _r;                                                         \
    } G_STMT_END
+
 #else
+
+/**
+ * GCAL_TODO:
+ * @_msg: the message to print
+ *
+ * Prints a TODO message.
+ */
 # define GCAL_TODO(_msg)
+
+/**
+ * GCAL_PROBE:
+ *
+ * Prints a probing message.
+ */
 # define GCAL_PROBE
+
+/**
+ * GCAL_TRACE_MSG:
+ * @fmt: printf-like format of the message
+ * @...: arguments for @fmt
+ *
+ * Prints a trace message.
+ */
 # define GCAL_TRACE_MSG(fmt, ...)
+
+/**
+ * GCAL_ENTRY:
+ *
+ * Prints a probing message. This shouldn't be used in
+ * critical functions. Place this at the beggining of
+ * the function, before any assertion.
+ */
 # define GCAL_ENTRY
+
+/**
+ * GCAL_GOTO:
+ * @_l: goto tag
+ *
+ * Logs a goto jump.
+ */
 # define GCAL_GOTO(_l)   goto _l
+
+/**
+ * GCAL_EXIT:
+ *
+ * Prints an exit message. This shouldn't be used in
+ * critical functions. Place this at the end of
+ * the function, after any relevant code. If the
+ * function returns somethin, use GCAL_RETURN()
+ * instead.
+ */
 # define GCAL_EXIT       return
+
+/**
+ * GCAL_RETURN:
+ * @_r: the return value.
+ *
+ * Prints an exit message, and returns @_r. See #GCAL_EXIT.
+ */
 # define GCAL_RETURN(_r) return _r
 #endif
 
+/**
+ * _GCAL_BUG: (skip)
+ */
 #define _GCAL_BUG(Component, Description, File, Line, Func, ...)                        \
   G_STMT_START {                                                                        \
     g_printerr ("-----------------------------------------------------------------\n"); \
@@ -91,6 +215,15 @@ G_BEGIN_DECLS
     g_printerr (Description"\n", ##__VA_ARGS__);                                        \
     g_printerr ("-----------------------------------------------------------------\n"); \
   } G_STMT_END
+
+/**
+ * GCAL_BUG:
+ * @Component: the component
+ * @Description: the description
+ * @...: extra arguments
+ *
+ * Logs a bug-friendly message.
+ */
 #define GCAL_BUG(Component, Description, ...) \
   _GCAL_BUG(Component, Description, __FILE__, __LINE__, G_STRFUNC, ##__VA_ARGS__)
 

src/gcal-edit-dialog.c

@@ -29,6 +29,17 @@
 #include <libecal/libecal.h>
 #include <glib/gi18n.h>
 
+/**
+ * SECTION:gcal-edit-dialog
+ * @short_description: Event editor dialog
+ * @title:GcalEditDialog
+ * @image:gcal-edit-dialog.png
+ *
+ * #GcalEditDialog is the event editor dialog of GNOME Calendar. It
+ * allows the user to change the various aspects of the events, as
+ * well as managing alarms.
+ */
+
 struct _GcalEditDialog
 {
   GtkDialog         parent;
@@ -766,6 +777,7 @@ get_row_for_alarm_trigger_minutes (GcalEditDialog *self,
 
   return NULL;
 }
+
 static void
 remove_button_clicked (GtkButton *button,
                        GtkWidget *row)
@@ -1019,12 +1031,27 @@ add_alarm_button_clicked (GtkWidget      *button,
 }
 
 /* Public API */
+
+/**
+ * gcal_edit_dialog_new:
+ *
+ * Creates a new #GcalEditDialog
+ *
+ * Returns: (transfer full): a #GcalEditDialog
+ */
 GtkWidget*
 gcal_edit_dialog_new (void)
 {
   return g_object_new (GCAL_TYPE_EDIT_DIALOG, NULL);
 }
 
+/**
+ * gcal_edit_dialog_set_time_format:
+ * @dialog: a #GcalDialog
+ * @use_24h_format: %TRUE to use 24h format, %FALSE otherwise
+ *
+ * Sets the time format to be used by @dialog.
+ */
 void
 gcal_edit_dialog_set_time_format (GcalEditDialog *dialog,
                                   gboolean        use_24h_format)
@@ -1037,6 +1064,14 @@ gcal_edit_dialog_set_time_format (GcalEditDialog *dialog,
   gcal_time_selector_set_time_format (GCAL_TIME_SELECTOR (dialog->end_time_selector), dialog->format_24h);
 }
 
+/**
+ * gcal_edit_dialog_set_event_is_new:
+ * @dialog: a #GcalDialog
+ * @event_is_new: %TRUE if the event is new, %FALSE otherwise
+ *
+ * Sets whether the currently edited event is a new event, or not.
+ * The @dialog will adapt it's UI elements to reflect that.
+ */
 void
 gcal_edit_dialog_set_event_is_new (GcalEditDialog *dialog,
                                    gboolean        event_is_new)
@@ -1046,6 +1081,14 @@ gcal_edit_dialog_set_event_is_new (GcalEditDialog *dialog,
   gtk_widget_set_visible (dialog->delete_button, !event_is_new);
 }
 
+/**
+ * gcal_edit_dialog_get_event:
+ * @dialog: a #GcalDialog
+ *
+ * Retrieves the current event being edited by the @dialog.
+ *
+ * Returns: (transfer none)(nullable): a #GcalEvent
+ */
 GcalEvent*
 gcal_edit_dialog_get_event (GcalEditDialog *dialog)
 {
@@ -1054,6 +1097,14 @@ gcal_edit_dialog_get_event (GcalEditDialog *dialog)
   return dialog->event;
 }
 
+/**
+ * gcal_edit_dialog_set_event:
+ * @dialog: a #GcalDialog
+ * @event: (nullable): a #GcalEvent
+ *
+ * Sets the event of the @dialog. When @event is
+ * %NULL, the current event information is unset.
+ */
 void
 gcal_edit_dialog_set_event (GcalEditDialog *dialog,
                             GcalEvent      *event)
@@ -1164,6 +1215,13 @@ out:
   GCAL_EXIT;
 }
 
+/**
+ * gcal_edit_dialog_set_manager:
+ * @dialog: a #GcalEditDialog
+ * @manager: a #GcalManager
+ *
+ * Sets the #GcalManager instance of the @dialog.
+ */
 void
 gcal_edit_dialog_set_manager (GcalEditDialog *dialog,
                               GcalManager    *manager)
@@ -1220,6 +1278,14 @@ return_datetime_for_widgets (GcalEditDialog   *dialog,
   return retval;
 }
 
+/**
+ * gcal_edit_dialog_get_date_start:
+ * @dialog: a #GcalEditDialog
+ *
+ * Retrieves the start date of the edit dialog.
+ *
+ * Returns: (transfer full): a #GDateTime
+ */
 GDateTime*
 gcal_edit_dialog_get_date_start (GcalEditDialog *dialog)
 {
@@ -1231,6 +1297,14 @@ gcal_edit_dialog_get_date_start (GcalEditDialog *dialog)
                                       GCAL_TIME_SELECTOR (dialog->start_time_selector));
 }
 
+/**
+ * gcal_edit_dialog_get_date_end:
+ * @dialog: a #GcalEditDialog
+ *
+ * Retrieves the end date of the edit dialog.
+ *
+ * Returns: (transfer full): a #GDateTime
+ */
 GDateTime*
 gcal_edit_dialog_get_date_end (GcalEditDialog *dialog)
 {

src/gcal-event.c

@@ -23,6 +23,58 @@
 
 #define LIBICAL_TZID_PREFIX "/freeassociation.sourceforge.net/"
 
+/**
+ * SECTION:gcal-event
+ * @short_description: A class that represents an event
+ * @title:GcalEvent
+ * @stability:unstable
+ * @see_also:GcalEventWidget,GcalManager
+ *
+ * The #GcalEvent class represents an appointment, with
+ * various functions to modify it. All the changes are
+ * transient. To persistently store the changes, you
+ * need to call gcal_manager_update_event().
+ *
+ * Although the #ECalComponent may have no end date. In this
+ * case, gcal_event_get_date_end() returns the same date that
+ * gcal_event_get_date_start().
+ *
+ * #GcalEvent implements #GInitable, and creating it possibly
+ * can generate an error. At the moment, the only error that
+ * can be generate is #GCAL_EVENT_ERROR_INVALID_START_DATE.
+ *
+ * ## Timezones
+ *
+ * When a #GcalEvent is created, the timezone is parsed from
+ * the #ECalComponent. The start and end dates can possibly
+ * have different timezones, e.g. when the user is traveling
+ * across timezones and the departure time is in a different
+ * timezone of the arrival time.
+ *
+ * For the sake of sanity, gcal_event_get_timezone() returns
+ * the timezone of the start date. If you need to precisely
+ * check the timezones of the start and end dates, you have
+ * to use g_date_time_get_timezone_identifier().
+ *
+ * ## Example:
+ * |[<!-- language="C" -->
+ * GcalEvent *event;
+ * GError *error;
+ *
+ * error = NULL;
+ * event = gcal_event_new (source, component, &error);
+ *
+ * if (error)
+ *   {
+ *     g_warning ("Error creating event: %s", error->message);
+ *     g_clear_error (&error);
+ *     return;
+ *   }
+ *
+ * ...
+ * ]|
+ */
+
 struct _GcalEvent
 {
   GObject             parent;
@@ -739,7 +791,7 @@ gcal_event_get_color (GcalEvent *self)
  * @color: a #GdkRGBA
  *
  * Sets the color of the event, which is passed to the
- * parent @ESource.
+ * parent #ESource.
  */
 void
 gcal_event_set_color (GcalEvent *self,
@@ -797,7 +849,9 @@ gcal_event_set_all_day (GcalEvent *self,
  * gcal_event_get_date_end:
  * @self: a #GcalEvent
  *
- * Retrieves the end date of @self.
+ * Retrieves the end date of @self. If the component doesn't
+ * have an end date, then the returned date is the same of
+ * gcal_event_get_date_start().
  *
  * Returns: (transfer none): a #GDateTime.
  */

src/gcal-event.h

@@ -26,6 +26,12 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GcalEventError:
+ * @GCAL_EVENT_ERROR_INVALID_START_DATE: indicated an invalid start date
+ *
+ * Errors that #GcalEvent can generate.
+ */
 typedef enum
 {
   GCAL_EVENT_ERROR_INVALID_START_DATE

src/gcal-manager.c

@@ -25,6 +25,17 @@
 
 #include <libedataserverui/libedataserverui.h>
 
+/**
+ * SECTION:gcal-manager
+ * @short_description: The backend of GNOME Calendar
+ * @title:GcalManager
+ * @stability:unstable
+ *
+ * #GcalManager is the backend of GNOME Calendar. It sets everything
+ * up, connects to the Online Accounts daemon, and manages the events
+ * and calendars.
+ */
+
 typedef struct
 {
   GcalEvent     *event;
@@ -479,7 +490,7 @@ on_event_created (GObject      *source_object,
 
 /**
  * on_component_updated:
- * @source_object: {@link ECalClient} source
+ * @source_object: #ECalClient source
  * @result: result of the operation
  * @user_data: manager instance
  *
@@ -510,9 +521,9 @@ on_event_updated (GObject      *source_object,
 
 /**
  * on_event_removed:
- * @source_object: {@link ECalClient} source
+ * @source_object: #ECalClient source
  * @result: result of the operation
- * @user_data: an {@link ECalComponent}
+ * @user_data: an #ECalComponent
  *
  * Called when an component is removed. Currently, it only checks for
  * error, but a more sophisticated implementation will come in no time.*
@@ -1076,12 +1087,12 @@ gcal_manager_init (GcalManager *self)
 /* Public API */
 /**
  * gcal_manager_new_with_settings:
- * @settings:
+ * @settings: a #GSettings
  *
- * Since: 0.0.1
+ * Creates a new #GcalManager with @settings.
- * Return value: the new #GcalManager
+ *
- * Returns: (transfer full):
+ * Returns: (transfer full): a newly created #GcalManager
- **/
+ */
 GcalManager*
 gcal_manager_new_with_settings (GSettings *settings)
 {
@@ -1092,29 +1103,32 @@ gcal_manager_new_with_settings (GSettings *settings)
 
 /**
  * gcal_manager_get_source:
- * @manager:
+ * @manager: a #GcalManager
+ * @uid: the unique identifier of the source
  *
  * Retrieve a source according to it's UID. The source
  * is referenced for thread-safety and must be unreferenced
  * after user.
  *
- * Returns: (Transfer full) an {@link ESource}, or NULL.
+ * Returns: (nullable)(transfer full): an #ESource, or %NULL.
- **/
+ */
 ESource*
 gcal_manager_get_source (GcalManager *manager,
                          const gchar *uid)
 {
+  g_return_val_if_fail (GCAL_IS_MANAGER (manager), NULL);
+
   return e_source_registry_ref_source (manager->source_registry, uid);
 }
 
 /**
  * gcal_manager_get_sources:
- * @manager:
+ * @manager: a #GcalManager
  *
  * Retrieve a list of the enabled sources used in the application.
  *
- * Returns: (Transfer full) a {@link GList} object to be freed with g_list_free()
+ * Returns: (nullable)(transfer container)(content-type ESource): a #GList
- **/
+ */
 GList*
 gcal_manager_get_sources (GcalManager *manager)
 {
@@ -1124,6 +1138,8 @@ gcal_manager_get_sources (GcalManager *manager)
 
   GCAL_ENTRY;
 
+  g_return_val_if_fail (GCAL_IS_MANAGER (manager), NULL);
+
   g_hash_table_iter_init (&iter, manager->clients);
 
   while (g_hash_table_iter_next (&iter, &key, &value))
@@ -1141,50 +1157,75 @@ gcal_manager_get_sources (GcalManager *manager)
 
 /**
  * gcal_manager_get_sources_connected:
- * @manager:
+ * @manager: a #GcalManager
  *
- * Returns a {@link GList} with every source connected on the app, whether they are enabled or not.
+ * Returns a #GList with every source connected on the app,
+ * whether they are enabled or not.
  *
- * Returns: (Transfer full) a {@link GList} object to be freed with g_list_free()
+ * Returns: (nullable)(transfer container)(content-type ESource): a #GList
- **/
+ */
 GList*
 gcal_manager_get_sources_connected (GcalManager *manager)
 {
+  g_return_val_if_fail (GCAL_IS_MANAGER (manager), NULL);
+
   return g_hash_table_get_keys (manager->clients);
 }
 
 /**
  * gcal_manager_get_default_source:
- * @manager: App singleton {@link GcalManager} instance
+ * @manager: a #GcalManager
  *
- * Returns: (Transfer full): an {@link ESource} object. Free with g_object_unref().
+ * Returns: (transfer full): an #ESource object. Free
- **/
+ * with g_object_unref().
+ */
 ESource*
 gcal_manager_get_default_source (GcalManager *manager)
 {
+  g_return_val_if_fail (GCAL_IS_MANAGER (manager), NULL);
+
   return e_source_registry_ref_default_calendar (manager->source_registry);
 }
 
 /**
  * gcal_manager_set_default_source:
- * @manager: App singleton {@link GcalManager} instance
+ * @manager: a #GcalManager
  * @source: the new default source.
  *
- * Returns:
+ * Sets the default calendar.
- **/
+ */
 void
 gcal_manager_set_default_source (GcalManager *manager,
                                  ESource     *source)
 {
+  g_return_if_fail (GCAL_IS_MANAGER (manager));
+
   e_source_registry_set_default_calendar (manager->source_registry, source);
 }
 
+/**
+ * gcal_manager_get_system_timezone:
+ * @manager: a #GcalManager
+ *
+ * Retireves the default timezone.
+ *
+ * Returns: (transfer none): the default timezone
+ */
 icaltimezone*
 gcal_manager_get_system_timezone (GcalManager *manager)
 {
+  g_return_val_if_fail (GCAL_IS_MANAGER (manager), NULL);
+
   return manager->system_timezone;
 }
 
+/**
+ * gcal_manager_setup_shell_search:
+ * @manager: a #GcalManager
+ * @subscriber: an #ECalDataModelSubscriber
+ *
+ * Sets up the GNOME Shell search subscriber.
+ */
 void
 gcal_manager_setup_shell_search (GcalManager             *self,
                                  ECalDataModelSubscriber *subscriber)
@@ -1213,13 +1254,15 @@ gcal_manager_setup_shell_search (GcalManager             *self,
  * @query: query string (an s-exp)
  *
  * Set the query terms of the #ECalDataModel used in the shell search
- **/
+ */
 void
 gcal_manager_set_shell_search_query (GcalManager *manager,
                                      const gchar *query)
 {
   GCAL_ENTRY;
 
+  g_return_if_fail (GCAL_IS_MANAGER (manager));
+
   manager->search_view_data->passed_start = FALSE;
   manager->search_view_data->search_done = FALSE;
   manager->search_view_data->sources_left = g_hash_table_size (manager->clients);
@@ -1231,6 +1274,15 @@ gcal_manager_set_shell_search_query (GcalManager *manager,
   e_cal_data_model_set_filter (manager->shell_search_data_model, query);
 }
 
+/**
+ * gcal_manager_set_shell_search_subscriber:
+ * @self: a #GcalManager
+ * @subscriber: the #ECalDataModelSubscriber to subscribe
+ * @range_start: the start of the range
+ * @range_end: the end of the range
+ *
+ * Subscribe @subscriber to the shell data modal at the given range.
+ */
 void
 gcal_manager_set_shell_search_subscriber (GcalManager             *manager,
                                           ECalDataModelSubscriber *subscriber,
@@ -1244,12 +1296,30 @@ gcal_manager_set_shell_search_subscriber (GcalManager             *manager,
   GCAL_EXIT;
 }
 
+/**
+ * gcal_manager_shell_search_done:
+ * @self: a #GcalManager
+ *
+ * Retrieves whether the search at @manager is done or not.
+ *
+ * Returns: %TRUE if the search is finished.
+ */
 gboolean
 gcal_manager_shell_search_done (GcalManager *manager)
 {
+  g_return_val_if_fail (GCAL_IS_MANAGER (manager), FALSE);
+
   return manager->search_view_data->search_done;
 }
 
+/**
+ * gcal_manager_get_shell_search_events:
+ * @self: a #GcalManager
+ *
+ * Retrieves all the events available for GNOME Shell search.
+ *
+ * Returns: (nullable)(transfer full)(content-type GcalEvent): a #GList
+ */
 GList*
 gcal_manager_get_shell_search_events (GcalManager *manager)
 {
@@ -1272,6 +1342,16 @@ gcal_manager_get_shell_search_events (GcalManager *manager)
   GCAL_RETURN (list);
 }
 
+/**
+ * gcal_manager_set_subscriber:
+ * @self: a #GcalManager
+ * @subscriber: a #ECalDataModelSubscriber
+ * @range_start: the start of the range
+ * @range_end: the end of the range
+ *
+ * Sets the @subscriber to show events between @range_start
+ * and @range_end.
+ */
 void
 gcal_manager_set_subscriber (GcalManager             *manager,
                              ECalDataModelSubscriber *subscriber,
@@ -1280,6 +1360,8 @@ gcal_manager_set_subscriber (GcalManager             *manager,
 {
   GCAL_ENTRY;
 
+  g_return_if_fail (GCAL_IS_MANAGER (manager));
+
   e_cal_data_model_subscribe (manager->e_data_model,
                               subscriber,
                               range_start,
@@ -1288,6 +1370,16 @@ gcal_manager_set_subscriber (GcalManager             *manager,
   GCAL_EXIT;
 }
 
+/**
+ * gcal_manager_set_search_subscriber:
+ * @self: a #GcalManager
+ * @subscriber: a #ECalDataModelSubscriber
+ * @range_start: the start of the range
+ * @range_end: the end of the range
+ *
+ * Sets the @subscriber to show events between @range_start
+ * and @range_end.
+ */
 void
 gcal_manager_set_search_subscriber (GcalManager             *manager,
                                     ECalDataModelSubscriber *subscriber,
@@ -1296,6 +1388,8 @@ gcal_manager_set_search_subscriber (GcalManager             *manager,
 {
   GCAL_ENTRY;
 
+  g_return_if_fail (GCAL_IS_MANAGER (manager));
+
   e_cal_data_model_subscribe (manager->search_data_model,
                               subscriber,
                               range_start,
@@ -1311,8 +1405,7 @@ gcal_manager_set_search_subscriber (GcalManager             *manager,
  *
  * Set the query terms of the #ECalDataModel or clear it if %NULL is
  * passed
- *
+ */
- **/
 void
 gcal_manager_set_query (GcalManager *self,
                         const gchar *query)
@@ -1330,10 +1423,10 @@ gcal_manager_set_query (GcalManager *self,
 /**
  * gcal_manager_query_client_data:
  *
- * Queries for a specific data field of
+ * Queries for a specific data field of the #ECalClient
- * the {@link ECalClient}.
  *
- * Returns: (Transfer none) a string representing the retrieved value, or NULL.
+ * Returns: (nullable)(transfer none): a string representing
+ * the retrieved value.
  */
 gchar*
 gcal_manager_query_client_data (GcalManager *manager,
@@ -1345,6 +1438,8 @@ gcal_manager_query_client_data (GcalManager *manager,
 
   GCAL_ENTRY;
 
+  g_return_val_if_fail (GCAL_IS_MANAGER (manager), NULL);
+
   unit = g_hash_table_lookup (manager->clients, source);
 
   if (!unit)
@@ -1365,10 +1460,8 @@ gcal_manager_query_client_data (GcalManager *manager,
  * Add a new calendar by its URI.
  * The calendar is enabled by default
  *
- * Return value: The UID of calendar's source, NULL in other case
+ * Returns: (nullable)(transfer full): unique identifier of calendar's source, or
- * Returns: (transfer full):
+ * %NULL.
- *
- * Since: 0.0.1
  */
 gchar*
 gcal_manager_add_source (GcalManager *manager,
@@ -1382,6 +1475,8 @@ gcal_manager_add_source (GcalManager *manager,
 
   GCAL_ENTRY;
 
+  g_return_val_if_fail (GCAL_IS_MANAGER (manager), NULL);
+
   source = e_source_new (NULL, NULL, NULL);
   extension = E_SOURCE_CALENDAR (e_source_get_extension (source, E_SOURCE_EXTENSION_CALENDAR));
 
@@ -1427,6 +1522,9 @@ gcal_manager_enable_source (GcalManager *manager,
 
   GCAL_ENTRY;
 
+  g_return_if_fail (GCAL_IS_MANAGER (manager));
+  g_return_if_fail (E_IS_SOURCE (source));
+
   unit = g_hash_table_lookup (manager->clients, source);
   selectable = e_source_get_extension (source, E_SOURCE_EXTENSION_CALENDAR);
 
@@ -1469,6 +1567,9 @@ gcal_manager_disable_source (GcalManager *manager,
 
   GCAL_ENTRY;
 
+  g_return_if_fail (GCAL_IS_MANAGER (manager));
+  g_return_if_fail (E_IS_SOURCE (source));
+
   unit = g_hash_table_lookup (manager->clients, source);
   selectable = e_source_get_extension (source, E_SOURCE_EXTENSION_CALENDAR);
 
@@ -1511,6 +1612,9 @@ gcal_manager_save_source (GcalManager *manager,
 
   GCAL_ENTRY;
 
+  g_return_if_fail (GCAL_IS_MANAGER (manager));
+  g_return_if_fail (E_IS_SOURCE (source));
+
   e_source_registry_commit_source_sync (manager->source_registry, source, NULL, &error);
 
   if (error)
@@ -1523,6 +1627,13 @@ gcal_manager_save_source (GcalManager *manager,
   GCAL_EXIT;
 }
 
+/**
+ * gcal_manager_refresh:
+ * @manager: a #GcalManager
+ *
+ * Forces a full refresh and synchronization of all available
+ * calendars.
+ */
 void
 gcal_manager_refresh (GcalManager *manager)
 {
@@ -1531,6 +1642,8 @@ gcal_manager_refresh (GcalManager *manager)
 
   GCAL_ENTRY;
 
+  g_return_if_fail (GCAL_IS_MANAGER (manager));
+
   clients = g_hash_table_get_values (manager->clients);
 
   /* refresh clients */
@@ -1552,6 +1665,15 @@ gcal_manager_refresh (GcalManager *manager)
   GCAL_EXIT;
 }
 
+/**
+ * gcal_manager_is_client_writable:
+ * @manager: a #GcalManager
+ * @source: an #ESource
+ *
+ * Retrieves whether @source is writable.
+ *
+ * Returns: %TRUE if @source is writable, %FALSE otherwise.
+ */
 gboolean
 gcal_manager_is_client_writable (GcalManager *manager,
                                  ESource     *source)
@@ -1568,9 +1690,16 @@ gcal_manager_is_client_writable (GcalManager *manager,
   GCAL_RETURN (unit->connected && !e_client_is_readonly (E_CLIENT (unit->client)));
 }
 
+/**
+ * gcal_manager_create_event:
+ * @manager: a #GcalManager
+ * @event: a #GcalEvent
+ *
+ * Creates @event.
+ */
 void
-gcal_manager_create_event (GcalManager        *manager,
+gcal_manager_create_event (GcalManager *manager,
-                           GcalEvent          *event)
+                           GcalEvent   *event)
 {
   GcalManagerUnit *unit;
   icalcomponent *new_event_icalcomp;
@@ -1580,6 +1709,9 @@ gcal_manager_create_event (GcalManager        *manager,
 
   GCAL_ENTRY;
 
+  g_return_if_fail (GCAL_IS_MANAGER (manager));
+  g_return_if_fail (GCAL_IS_EVENT (event));
+
   source = gcal_event_get_source (event);
   component = gcal_event_get_component (event);
   unit = g_hash_table_lookup (manager->clients, source);
@@ -1599,6 +1731,13 @@ gcal_manager_create_event (GcalManager        *manager,
   GCAL_EXIT;
 }
 
+/**
+ * gcal_manager_update_event:
+ * @manager: a #GcalManager
+ * @event: a #GcalEvent
+ *
+ * Saves all changes made to @event persistently.
+ */
 void
 gcal_manager_update_event (GcalManager *manager,
                            GcalEvent   *event)
@@ -1608,6 +1747,9 @@ gcal_manager_update_event (GcalManager *manager,
 
   GCAL_ENTRY;
 
+  g_return_if_fail (GCAL_IS_MANAGER (manager));
+  g_return_if_fail (GCAL_IS_EVENT (event));
+
   unit = g_hash_table_lookup (manager->clients, gcal_event_get_source (event));
   component = gcal_event_get_component (event);
 
@@ -1628,9 +1770,16 @@ gcal_manager_update_event (GcalManager *manager,
   GCAL_EXIT;
 }
 
+/**
+ * gcal_manager_remove_event:
+ * @manager: a #GcalManager
+ * @event: a #GcalEvent
+ *
+ * Deletes @event.
+ */
 void
-gcal_manager_remove_event (GcalManager   *manager,
+gcal_manager_remove_event (GcalManager *manager,
-                           GcalEvent     *event)
+                           GcalEvent   *event)
 {
   GcalManagerUnit *unit;
   ECalComponentId *id;
@@ -1638,6 +1787,9 @@ gcal_manager_remove_event (GcalManager   *manager,
 
   GCAL_ENTRY;
 
+  g_return_if_fail (GCAL_IS_MANAGER (manager));
+  g_return_if_fail (GCAL_IS_EVENT (event));
+
   component = gcal_event_get_component (event);
   unit = g_hash_table_lookup (manager->clients, gcal_event_get_source (event));
   id = e_cal_component_get_id (component);
@@ -1662,6 +1814,16 @@ gcal_manager_remove_event (GcalManager   *manager,
   GCAL_EXIT;
 }
 
+/**
+ * gcal_manager_move_event_to_source:
+ * @manager: a #GcalManager
+ * @event: a #GcalEvent
+ * @dest: the destination calendar
+ *
+ * Moves @event to @dest calendar. This is a fail-safe operation:
+ * worst case, the user will have two duplicated events, and we
+ * guarantee to never loose any data.
+ */
 void
 gcal_manager_move_event_to_source (GcalManager *manager,
                                    GcalEvent   *event,
@@ -1677,6 +1839,8 @@ gcal_manager_move_event_to_source (GcalManager *manager,
   GCAL_ENTRY;
 
   g_return_if_fail (GCAL_IS_MANAGER (manager));
+  g_return_if_fail (GCAL_IS_EVENT (event));
+  g_return_if_fail (E_IS_SOURCE (dest));
 
   error = NULL;
 
@@ -1732,11 +1896,15 @@ gcal_manager_move_event_to_source (GcalManager *manager,
 
 /**
  * gcal_manager_get_events:
+ * @manager: a #GcalManager
+ * @start_date: the start of the dete range
+ * @end_date: the end of the dete range
  *
- * Returns a list with {@link GcalEvent} objects owned by the caller, the list and the objects.
+ * Returns a list with #GcalEvent objects owned by the caller,
- * The components inside the list are owned by the caller as well. So, don't ref the component.
+ * the list and the objects. The components inside the list are
+ * owned by the caller as well.
  *
- * Returns: An {@link GList} object
+ * Returns: (nullable)(transfer full)(content-type GcalEvent):a #GList
  */
 GList*
 gcal_manager_get_events (GcalManager  *manager,
@@ -1748,14 +1916,30 @@ gcal_manager_get_events (GcalManager  *manager,
 
   GCAL_ENTRY;
 
+  g_return_val_if_fail (GCAL_IS_MANAGER (manager), NULL);
+
   range_start = icaltime_as_timet_with_zone (*start_date, manager->system_timezone);
   range_end = icaltime_as_timet_with_zone (*end_date, manager->system_timezone);
 
-  e_cal_data_model_foreach_component (manager->e_data_model, range_start, range_end, gather_events, &list);
+  e_cal_data_model_foreach_component (manager->e_data_model,
+                                      range_start,
+                                      range_end,
+                                      gather_events,
+                                      &list);
 
   GCAL_RETURN (list);
 }
 
+/**
+ * gcal_manager_get_loading:
+ * @self: a #GcalManager
+ *
+ * Retrieves whether @self is still loading or not. Loading is
+ * complete when the Online Accounts client is retrieved, and all
+ * the calendars are loaded.
+ *
+ * Returns: %TRUE if manager is still loading; %FALSE otherwise
+ */
 gboolean
 gcal_manager_get_loading (GcalManager *self)
 {
@@ -1764,6 +1948,15 @@ gcal_manager_get_loading (GcalManager *self)
   return !self->goa_client_ready || self->sources_at_launch > 0;
 }
 
+/**
+ * gcal_manager_get_event_from_shell_search:
+ * @manager: a #GcalManager
+ * @uuid: the unique identier of the event
+ *
+ * Retrieves the #GcalEvent with @uuid.
+ *
+ * Returns: (nullable)(transfer full): a #GcalEvent
+ */
 GcalEvent*
 gcal_manager_get_event_from_shell_search (GcalManager *manager,
                                           const gchar *uuid)
@@ -1774,12 +1967,21 @@ gcal_manager_get_event_from_shell_search (GcalManager *manager,
 
   GCAL_ENTRY;
 
+  g_return_val_if_fail (GCAL_IS_MANAGER (manager), NULL);
+
   list = NULL;
   new_event = NULL;
 
-  e_cal_data_model_get_subscriber_range (manager->shell_search_data_model, manager->search_view_data->subscriber,
+  e_cal_data_model_get_subscriber_range (manager->shell_search_data_model,
-                                         &range_start, &range_end);
+                                         manager->search_view_data->subscriber,
-  e_cal_data_model_foreach_component (manager->shell_search_data_model, range_start, range_end, gather_events, &list);
+                                         &range_start,
+                                         &range_end);
+
+  e_cal_data_model_foreach_component (manager->shell_search_data_model,
+                                      range_start,
+                                      range_end,
+                                      gather_events,
+                                      &list);
 
   for (l = list; l != NULL; l = g_list_next (l))
     {
@@ -1799,12 +2001,20 @@ gcal_manager_get_event_from_shell_search (GcalManager *manager,
   GCAL_RETURN (new_event);
 }
 
+/**
+ * gcal_manager_get_goa_client:
+ * @self: a #GcalManager
+ *
+ * Retrieves the #GoaClient connected by @self.
+ *
+ * Returns: (transfer none): a #GoaClient
+ */
 GoaClient*
-gcal_manager_get_goa_client (GcalManager *manager)
+gcal_manager_get_goa_client (GcalManager *self)
 {
-  g_return_val_if_fail (GCAL_IS_MANAGER (manager), FALSE);
-
   GCAL_ENTRY;
 
-  GCAL_RETURN (manager->goa_client);
+  g_return_val_if_fail (GCAL_IS_MANAGER (self), NULL);
+
+  GCAL_RETURN (self->goa_client);
 }

src/gcal-source-dialog.c

@@ -26,6 +26,19 @@
 #include <goa/goa.h>
 #include <libedataserverui/libedataserverui.h>
 
+/**
+ * SECTION:gcal-source-dialog
+ * @short_description: Dialog to manage calendars
+ * @title:GcalSourceDialog
+ * @stability:unstable
+ * @image:gcal-source-dialog.png
+ *
+ * #GcalSourceDialog is the calendar management widget of GNOME
+ * Calendar. With it, users can create calendars from local files,
+ * local calendars or even import calendars from the Web or their
+ * online accounts.
+ */
+
 struct _GcalSourceDialog
 {
   GtkDialog           parent;
@@ -239,7 +252,7 @@ add_button_clicked (GtkWidget *button,
 
   if (self->source != NULL)
     {
-      // Commit the new source
+      /* Commit the new source */
       gcal_manager_save_source (self->manager, self->source);
 
       self->source = NULL;
@@ -251,14 +264,14 @@ add_button_clicked (GtkWidget *button,
     {
       GList *l;
 
-      // Commit each new remote source
+      /* Commit each new remote source */
       for (l = self->remote_sources; l != NULL; l = l->next)
         gcal_manager_save_source (self->manager, l->data);
 
       g_list_free (self->remote_sources);
       self->remote_sources = NULL;
 
-      // Go back to overview
+      /* Go back to overview */
       gcal_source_dialog_set_mode (GCAL_SOURCE_DIALOG (user_data), GCAL_SOURCE_DIALOG_MODE_NORMAL);
     }
 }
@@ -311,16 +324,6 @@ add_source (GcalManager *manager,
   g_list_free (children);
 }
 
-/**
- * action_widget_activated:
- * @widget: the button which emited the signal.
- * @user_data: a {@link GcalSourceDialog} instance.
- *
- * Emit a response when action buttons
- * are clicked.
- *
- * Returns:
- */
 static void
 action_widget_activated (GtkWidget *widget,
                          gpointer   user_data)
@@ -333,13 +336,6 @@ action_widget_activated (GtkWidget *widget,
   gtk_dialog_response (GTK_DIALOG (user_data), response);
 }
 
-/**
- * back_button_clicked:
- *
- * Returns to the previous page.
- *
- * Returns:
- */
 static void
 back_button_clicked (GtkButton *button,
                      gpointer   user_data)
@@ -348,10 +344,10 @@ back_button_clicked (GtkButton *button,
 
   if (gtk_stack_get_visible_child (GTK_STACK (self->stack)) == self->edit_grid)
     {
-      // Save the source before leaving
+      /* Save the source before leaving */
       gcal_manager_save_source (self->manager, self->source);
 
-      // Release the source ref we acquired
+      /* Release the source ref we acquired */
       g_clear_object (&self->source);
     }
 
@@ -370,11 +366,11 @@ calendar_listbox_sort_func (GtkListBoxRow *row1,
 
   self = GCAL_SOURCE_DIALOG (user_data);
 
-  // first source
+  /* first source */
   source1 = g_object_get_data (G_OBJECT (row1), "source");
   is_goa1 = is_goa_source (GCAL_SOURCE_DIALOG (user_data), source1);
 
-  // second source
+  /* second source */
   source2 = g_object_get_data (G_OBJECT (row2), "source");
   is_goa2 = is_goa_source (GCAL_SOURCE_DIALOG (user_data), source2);
 
@@ -383,13 +379,13 @@ calendar_listbox_sort_func (GtkListBoxRow *row1,
       gchar *parent_name1 = NULL;
       gchar *parent_name2 = NULL;
 
-      // Retrieve parent names
+      /* Retrieve parent names */
       get_source_parent_name_color (self->manager, source1, &parent_name1, NULL);
       get_source_parent_name_color (self->manager, source2, &parent_name2, NULL);
 
       retval = g_strcmp0 (parent_name1, parent_name2);
 
-      // If they have the same parent names, compare by the source display names
+      /* If they have the same parent names, compare by the source display names */
       if (retval == 0)
         retval = g_strcmp0 (e_source_get_display_name (source1), e_source_get_display_name (source2));
 
@@ -398,7 +394,7 @@ calendar_listbox_sort_func (GtkListBoxRow *row1,
     }
   else
     {
-      // If one is a GOA account and the other isn't, make the GOA one go first
+      /* If one is a GOA account and the other isn't, make the GOA one go first */
       retval = is_goa1 ? -1 : 1;
     }
 
@@ -424,10 +420,10 @@ cancel_button_clicked (GtkWidget *button,
 {
   GcalSourceDialog *self = GCAL_SOURCE_DIALOG (user_data);
 
-  // Destroy the ongoing created source
+  /* Destroy the ongoing created source */
   g_clear_object (&self->source);
 
-  // Cleanup detected remote sources that weren't added
+  /* Cleanup detected remote sources that weren't added */
   if (self->remote_sources != NULL)
     {
       g_list_free_full (self->remote_sources, g_object_unref);
@@ -437,13 +433,6 @@ cancel_button_clicked (GtkWidget *button,
   gcal_source_dialog_set_mode (GCAL_SOURCE_DIALOG (user_data), GCAL_SOURCE_DIALOG_MODE_NORMAL);
 }
 
-/**
- * clear_pages:
- *
- * Clear local and web pages.
- *
- * Returns:
- */
 static void
 clear_pages (GcalSourceDialog *dialog)
 {
@@ -452,7 +441,7 @@ clear_pages (GcalSourceDialog *dialog)
   gtk_entry_set_text (GTK_ENTRY (dialog->calendar_address_entry), "");
   gtk_widget_set_sensitive (dialog->add_button, FALSE);
 
-  // Remove discovered web sources (if any)
+  /* Remove discovered web sources (if any) */
   list = gtk_container_get_children (GTK_CONTAINER (dialog->web_sources_listbox));
   g_list_free_full (list, (GDestroyNotify) gtk_widget_destroy);
 
@@ -500,15 +489,6 @@ default_check_toggled (GObject    *object,
     gcal_manager_set_default_source (self->manager, self->old_default_source);
 }
 
-
-/**
- * description_label_link_activated:
- *
- * Show GNOME Control Center when
- * the label's link is pressed.
- *
- * Returns:
- */
 static gboolean
 description_label_link_activated (GtkWidget *widget,
                                   gchar     *uri,
@@ -520,12 +500,6 @@ description_label_link_activated (GtkWidget *widget,
   return TRUE;
 }
 
-/**
- * display_header_func:
- *
- * Shows a separator before each row.
- *
- */
 static void
 display_header_func (GtkListBoxRow *row,
                      GtkListBoxRow *before,
@@ -540,14 +514,6 @@ display_header_func (GtkListBoxRow *row,
     }
 }
 
-/**
- * is_goa_source:
- *
- * Checks whether the source comes from
- * a online account.
- *
- * Returns: %TRUE if the source came from a GOA account
- */
 static gboolean
 is_goa_source (GcalSourceDialog *dialog,
                ESource          *source)
@@ -599,14 +565,6 @@ invalidate_calendar_listbox_sort (GObject    *source,
   gtk_list_box_invalidate_sort (GTK_LIST_BOX (user_data));
 }
 
-/**
- * make_row_from_source:
- *
- * Create a GtkListBoxRow for a given
- * ESource.
- *
- * Returns: (transfer full) the new row
- */
 static GtkWidget*
 make_row_from_source (GcalSourceDialog *dialog,
                       ESource          *source)
@@ -658,17 +616,6 @@ make_row_from_source (GcalSourceDialog *dialog,
   return row;
 }
 
-/**
- * name_entry_text_changed:
- *
- * Callend when the name entry's text
- * is edited. It changes the source's
- * display name, but wait's for the
- * calendar's ::response signal to
- * commit these changes.
- *
- * Returns:
- */
 static void
 name_entry_text_changed (GObject    *object,
                          GParamSpec *pspec,
@@ -677,6 +624,14 @@ name_entry_text_changed (GObject    *object,
   GcalSourceDialog *self = GCAL_SOURCE_DIALOG (user_data);
   gboolean valid = gtk_entry_get_text_length (GTK_ENTRY (object)) > 0;
 
+  /*
+   * Callend when the name entry's text
+   * is edited. It changes the source's
+   * display name, but wait's for the
+   * calendar's ::response signal to
+   * commit these changes.
+   */
+
   gtk_widget_set_sensitive (self->back_button, valid);
   gtk_widget_set_sensitive (self->add_button, valid);
 
@@ -695,13 +650,6 @@ spawn_goa_with_args (const gchar *action,
                  NULL, NULL, NULL, NULL);
 }
 
-/**
- * online_accounts_listbox_row_activated:
- *
- * Selects the online account, or add one.
- *
- * Returns:
- */
 static void
 online_accounts_listbox_row_activated (GtkListBox    *box,
                                        GtkListBoxRow *row,
@@ -736,14 +684,6 @@ online_accounts_listbox_row_activated (GtkListBox    *box,
     }
 }
 
-/**
- * response_signal:
- *
- * Save the source when the dialog
- * is close.
- *
- * Returns:
- */
 static void
 response_signal (GtkDialog *dialog,
                  gint       response_id,
@@ -751,19 +691,19 @@ response_signal (GtkDialog *dialog,
 {
   GcalSourceDialog *self = GCAL_SOURCE_DIALOG (dialog);
 
-  /* save the source */
+  /* Save the source */
   if (self->mode == GCAL_SOURCE_DIALOG_MODE_EDIT && self->source != NULL)
     {
       gcal_manager_save_source (self->manager, self->source);
       g_clear_object (&self->source);
     }
 
-  /* commit the new source; save the current page's source */
+  /* Commit the new source; save the current page's source */
   if (self->mode == GCAL_SOURCE_DIALOG_MODE_NORMAL && response_id == GTK_RESPONSE_APPLY && self->remote_sources != NULL)
       {
         GList *l;
 
-        // Commit each new remote source
+        /* Commit each new remote source */
         for (l = self->remote_sources; l != NULL; l = l->next)
           gcal_manager_save_source (self->manager, l->data);
 
@@ -800,7 +740,7 @@ is_remote_source (ESource *source)
 
       auth = e_source_get_extension (source, E_SOURCE_EXTENSION_AUTHENTICATION);
 
-      // No host is set, it's not a remote source
+      /* No host is set, it's not a remote source */
       if (e_source_authentication_get_host (auth) == NULL)
         return FALSE;
     }
@@ -811,7 +751,7 @@ is_remote_source (ESource *source)
 
       webdav = e_source_get_extension (source, E_SOURCE_EXTENSION_WEBDAV_BACKEND);
 
-      // No resource path specified, not a remote source
+      /* No resource path specified, not a remote source */
       if (e_source_webdav_get_resource_path (webdav) == NULL)
         return FALSE;
     }
@@ -876,7 +816,7 @@ stack_visible_child_name_changed (GObject    *object,
 
       get_source_parent_name_color (self->manager, self->source, &parent_name, NULL);
 
-      // update headerbar buttons
+      /* update headerbar buttons */
       gtk_header_bar_set_show_close_button (GTK_HEADER_BAR (self->headerbar), !creation_mode);
       gtk_widget_set_visible (self->calendar_visible_check, !creation_mode);
       gtk_widget_set_visible (self->back_button, !creation_mode);
@@ -885,7 +825,7 @@ stack_visible_child_name_changed (GObject    *object,
       gtk_widget_set_visible (self->account_box, is_goa);
       gtk_widget_set_visible (self->calendar_url_button, !is_goa && (is_file || is_remote));
 
-      // If it's a file, set the file path
+      /* If it's a file, set the file path */
       if (is_file)
         {
           ESourceLocal *local;
@@ -902,7 +842,7 @@ stack_visible_child_name_changed (GObject    *object,
           g_free (uri);
         }
 
-      // If it's remote, build the uri
+      /* If it's remote, build the uri */
       if (is_remote)
         {
           ESourceAuthentication *auth;
@@ -940,7 +880,7 @@ stack_visible_child_name_changed (GObject    *object,
       /* entry */
       gtk_entry_set_text (GTK_ENTRY (self->name_entry), e_source_get_display_name (self->source));
 
-      // enabled check
+      /* enabled check */
       gtk_toggle_button_set_active (GTK_TOGGLE_BUTTON (self->calendar_visible_check),
                                     is_source_enabled (self->source));
 
@@ -968,14 +908,6 @@ stack_visible_child_name_changed (GObject    *object,
     }
 }
 
-/**
- * calendar_file_selected:
- *
- * Opens a file selector dialog and
- * parse the resulting selection.
- *
- * Returns:
- */
 static void
 calendar_file_selected (GtkFileChooser *button,
                         gpointer        user_data)
@@ -1007,23 +939,13 @@ calendar_file_selected (GtkFileChooser *button,
   /* update the source properties */
   e_source_set_display_name (source, g_file_get_basename (file));
 
-  // Jump to the edit page
+  /* Jump to the edit page */
   gcal_source_dialog_set_source (GCAL_SOURCE_DIALOG (user_data), source);
   gcal_source_dialog_set_mode (GCAL_SOURCE_DIALOG (user_data), GCAL_SOURCE_DIALOG_MODE_CREATE);
 
   gtk_widget_set_sensitive (self->add_button, TRUE);
 }
 
-/**
- * calendar_listbox_row_activated:
- *
- * Edits the selected calendar for the
- * 'Calendars' listbox or goes to the
- * calendar selection for the Online
- * Accounts listbox.
- *
- * Returns:
- */
 static void
 calendar_listbox_row_activated (GtkListBox    *box,
                                 GtkListBoxRow *row,
@@ -1046,13 +968,6 @@ calendar_listbox_row_activated (GtkListBox    *box,
     }
 }
 
-/**
- * pulse_web_entry:
- *
- * Update the url's entry with a pulse fraction.
- *
- * Returns: FALSE
- */
 static gboolean
 pulse_web_entry (GcalSourceDialog *dialog)
 {
@@ -1063,14 +978,6 @@ pulse_web_entry (GcalSourceDialog *dialog)
   return FALSE;
 }
 
-/**
- * url_entry_text_changed:
- *
- * Performs a validation of the URL
- * 1 second after the user inputs.
- *
- * Returns:
- */
 static void
 url_entry_text_changed (GObject    *object,
                         GParamSpec *pspec,
@@ -1098,7 +1005,7 @@ url_entry_text_changed (GObject    *object,
 
   if (g_utf8_strlen (text, -1) != 0)
     {
-      // Remove any previous unreleased resource
+      /* Remove any previous unreleased resource */
       if (self->validate_url_resource_id != 0)
         g_source_remove (self->validate_url_resource_id);
 
@@ -1117,14 +1024,6 @@ url_entry_text_changed (GObject    *object,
     }
 }
 
-/**
- * online_accounts_settings_button_clicked:
- *
- * Spawns the GNOME Control Center app
- * with Online Accounts openned.
- *
- * Returns:
- */
 static void
 online_accounts_settings_button_clicked (GtkWidget *button,
                                          gpointer   user_data)
@@ -1141,7 +1040,7 @@ on_file_activated (GSimpleAction *action,
   GtkFileFilter *filter;
   gint response;
 
-  // Dialog
+  /* Dialog */
   dialog = gtk_file_chooser_dialog_new (_("Select a calendar file"),
                                         GTK_WINDOW (gtk_widget_get_toplevel (GTK_WIDGET (user_data))),
                                         GTK_FILE_CHOOSER_ACTION_SAVE,
@@ -1151,7 +1050,7 @@ on_file_activated (GSimpleAction *action,
 
   g_signal_connect (dialog, "file-activated", G_CALLBACK (calendar_file_selected), user_data);
 
-  // File filter
+  /* File filter */
   filter = gtk_file_filter_new ();
   gtk_file_filter_set_name (filter, _("Calendar files"));
   gtk_file_filter_add_mime_type (filter, "text/calendar");
@@ -1166,14 +1065,6 @@ on_file_activated (GSimpleAction *action,
   gtk_widget_destroy (dialog);
 }
 
-/**
- * on_local_activated:
- *
- * Creates a new local calendar, and let
- * the user adjust the settings after.
- *
- * Returns:
- */
 static void
 on_local_activated (GSimpleAction *action,
                     GVariant      *param,
@@ -1197,21 +1088,13 @@ on_local_activated (GSimpleAction *action,
   /* update the source properties */
   e_source_set_display_name (source, _("Unnamed Calendar"));
 
-  // Jump to the edit page
+  /* Jump to the edit page */
   gcal_source_dialog_set_source (GCAL_SOURCE_DIALOG (user_data), source);
   gcal_source_dialog_set_mode (GCAL_SOURCE_DIALOG (user_data), GCAL_SOURCE_DIALOG_MODE_CREATE);
 
   gtk_widget_set_sensitive (self->add_button, TRUE);
 }
 
-/**
- * on_web_activated:
- *
- * Redirect to the web calendar creation
- * page
- *
- * Returns:
- */
 static void
 on_web_activated (GSimpleAction *action,
                   GVariant      *param,
@@ -1229,14 +1112,6 @@ calendar_address_activated (GtkEntry *entry,
   validate_url_cb (GCAL_SOURCE_DIALOG (user_data));
 }
 
-/**
- * validate_url_cb:
- *
- * Query the given URL for possible
- * calendar data.
- *
- * Returns:FALSE
- */
 static gboolean
 validate_url_cb (GcalSourceDialog *dialog)
 {
@@ -1260,15 +1135,15 @@ validate_url_cb (GcalSourceDialog *dialog)
       dialog->remote_sources = NULL;
     }
 
-  // Remove previous results
+  /* Remove previous results */
   g_list_free_full (gtk_container_get_children (GTK_CONTAINER (dialog->web_sources_listbox)),
                     (GDestroyNotify) gtk_widget_destroy);
   gtk_revealer_set_reveal_child (GTK_REVEALER (dialog->web_sources_revealer), FALSE);
 
-  // Clear the entry icon
+  /* Clear the entry icon */
   gtk_entry_set_icon_from_icon_name (GTK_ENTRY (dialog->calendar_address_entry), GTK_ENTRY_ICON_SECONDARY, NULL);
 
-  // Get the hostname and file path from the server
+  /* Get the hostname and file path from the server */
   uri_valid = uri_get_fields (gtk_entry_get_text (GTK_ENTRY (dialog->calendar_address_entry)), NULL, &host, &path);
 
   g_debug ("[source-dialog] host: '%s', path: '%s'", host, path);
@@ -1286,11 +1161,11 @@ validate_url_cb (GcalSourceDialog *dialog)
   ext = e_source_get_extension (source, E_SOURCE_EXTENSION_CALENDAR);
   e_source_backend_set_backend_name (E_SOURCE_BACKEND (ext), "webcal");
 
-  // Authentication
+  /* Authentication */
   auth = e_source_get_extension (source, E_SOURCE_EXTENSION_AUTHENTICATION);
   e_source_authentication_set_host (auth, host);
 
-  // Webdav
+  /* Webdav */
   webdav = e_source_get_extension (source, E_SOURCE_EXTENSION_WEBDAV_BACKEND);
   e_source_webdav_set_resource_path (webdav, path);
 
@@ -1301,17 +1176,17 @@ validate_url_cb (GcalSourceDialog *dialog)
    */
   if (g_str_has_suffix (path, ".ics"))
     {
-      // Set the private source so it saves at closing
+      /* Set the private source so it saves at closing */
       dialog->remote_sources = g_list_append (dialog->remote_sources, source);
 
-      // Update buttons
+      /* Update buttons */
       gtk_widget_set_sensitive (dialog->add_button, source != NULL);
     }
   else
     {
       ENamedParameters *credentials;
 
-      // Pulse the entry while it performs the check
+      /* Pulse the entry while it performs the check */
       dialog->calendar_address_id = g_timeout_add (ENTRY_PROGRESS_TIMEOUT, (GSourceFunc) pulse_web_entry, dialog);
 
       /*
@@ -1325,7 +1200,7 @@ validate_url_cb (GcalSourceDialog *dialog)
         {
           g_debug ("[source-dialog] Trying to connect without credentials...");
 
-          // NULL credentials
+          /* NULL credentials */
           e_named_parameters_set (credentials, E_SOURCE_CREDENTIAL_USERNAME, NULL);
           e_named_parameters_set (credentials, E_SOURCE_CREDENTIAL_PASSWORD, NULL);
 
@@ -1349,7 +1224,7 @@ validate_url_cb (GcalSourceDialog *dialog)
            */
           if (response == GTK_RESPONSE_OK)
             {
-              // User inputted credentials
+              /* User inputted credentials */
               e_named_parameters_set (credentials, E_SOURCE_CREDENTIAL_USERNAME, user);
               e_named_parameters_set (credentials, E_SOURCE_CREDENTIAL_PASSWORD, password);
 
@@ -1398,13 +1273,13 @@ prompt_credentials (GcalSourceDialog  *dialog,
 {
   gint response;
 
-  // Cleanup last credentials
+  /* Cleanup last credentials */
   gtk_entry_set_text (GTK_ENTRY (dialog->credentials_password_entry), "");
   gtk_entry_set_text (GTK_ENTRY (dialog->credentials_user_entry), "");
 
   gtk_widget_grab_focus (dialog->credentials_user_entry);
 
-  // Show the dialog, then destroy it
+  /* Show the dialog, then destroy it */
   response = gtk_dialog_run (GTK_DIALOG (dialog->credentials_dialog));
 
   if (response == GTK_RESPONSE_OK)
@@ -1435,7 +1310,7 @@ duplicate_source (ESource *source)
   ext = e_source_get_extension (new_source, E_SOURCE_EXTENSION_CALENDAR);
   e_source_backend_set_backend_name (E_SOURCE_BACKEND (ext), "local");
 
-  // Copy Authentication data
+  /* Copy Authentication data */
   if (e_source_has_extension (source, E_SOURCE_EXTENSION_AUTHENTICATION))
     {
       ESourceAuthentication *new_auth, *parent_auth;
@@ -1450,7 +1325,7 @@ duplicate_source (ESource *source)
       e_source_authentication_set_proxy_uid (new_auth, e_source_authentication_get_proxy_uid (parent_auth));
     }
 
-  // Copy Webdav data
+  /* Copy Webdav data */
   if (e_source_has_extension (source, E_SOURCE_EXTENSION_WEBDAV_BACKEND))
     {
       ESourceWebdav *new_webdav, *parent_webdav;
@@ -1507,7 +1382,7 @@ discover_sources_cb (GObject      *source,
   self = GCAL_SOURCE_DIALOG (user_data);
   error = NULL;
 
-  // Stop the pulsing entry
+  /* Stop the pulsing entry */
   if (self->calendar_address_id != 0)
     {
       gtk_entry_set_progress_fraction (GTK_ENTRY (self->calendar_address_entry), 0);
@@ -1518,7 +1393,7 @@ discover_sources_cb (GObject      *source,
   if (!e_webdav_discover_sources_finish (E_SOURCE (source), result, NULL, NULL, &discovered_sources, &user_addresses,
                                         &error))
     {
-      // Don't add an source with errors
+      /* Don't add an source with errors */
       gtk_widget_set_sensitive (self->add_button, FALSE);
 
       /*
@@ -1543,15 +1418,15 @@ discover_sources_cb (GObject      *source,
       return;
     }
 
-  // Add a success icon to the entry
+  /* Add a success icon to the entry */
   gtk_entry_set_icon_from_icon_name (GTK_ENTRY (self->calendar_address_entry), GTK_ENTRY_ICON_SECONDARY,
                                      "emblem-ok-symbolic");
 
-  // Remove previous results
+  /* Remove previous results */
   g_list_free_full (gtk_container_get_children (GTK_CONTAINER (self->web_sources_listbox)),
                     (GDestroyNotify) gtk_widget_destroy);
 
-  // Show the list of calendars
+  /* Show the list of calendars */
   gtk_revealer_set_reveal_child (GTK_REVEALER (self->web_sources_revealer), TRUE);
   gtk_widget_show (self->web_sources_revealer);
 
@@ -1563,7 +1438,7 @@ discover_sources_cb (GObject      *source,
 
       src = aux->data;
 
-      // Get the new resource path from the uri
+      /* Get the new resource path from the uri */
       uri_valid = uri_get_fields (src->href, NULL, NULL, &resource_path);
 
       if (uri_valid)
@@ -1606,7 +1481,7 @@ discover_sources_cb (GObject      *source,
       g_free (resource_path);
     }
 
-  // Free things up
+  /* Free things up */
   e_webdav_discover_free_discovered_sources (discovered_sources);
   g_slist_free_full (user_addresses, g_free);
 }
@@ -1671,7 +1546,7 @@ notification_child_revealed_changed (GtkWidget  *notification,
       if (!e_source_get_removable (self->removed_source))
         return;
 
-      // Enable the source again to remove it's name from disabled list
+      /* Enable the source again to remove it's name from disabled list */
       gcal_manager_enable_source (self->manager, self->removed_source);
 
       e_source_remove_sync (self->removed_source, NULL, &error);
@@ -1712,7 +1587,7 @@ undo_remove_action (GtkButton *button,
   /* if there's any set source, unremove it */
   if (self->removed_source != NULL)
     {
-      // Enable the source before adding it again
+      /* Enable the source before adding it again */
       gcal_manager_enable_source (self->manager, self->removed_source);
 
       add_source (self->manager,
@@ -1726,7 +1601,7 @@ undo_remove_action (GtkButton *button,
        */
       self->removed_source = NULL;
 
-      // Hide notification
+      /* Hide notification */
       gtk_revealer_set_reveal_child (GTK_REVEALER (self->notification), FALSE);
     }
 }
@@ -1788,7 +1663,7 @@ remove_button_clicked (GtkWidget *button,
 
       gtk_revealer_set_reveal_child (GTK_REVEALER (self->notification), TRUE);
 
-      // Remove the listbox entry (if any)
+      /* Remove the listbox entry (if any) */
       for (l = children; l != NULL; l = l->next)
         {
           if (g_object_get_data (l->data, "source") == self->removed_source)
@@ -1798,17 +1673,17 @@ remove_button_clicked (GtkWidget *button,
             }
         }
 
-      // Update notification label
+      /* Update notification label */
       str = g_markup_printf_escaped (_("Calendar <b>%s</b> removed"), e_source_get_display_name (self->removed_source));
       gtk_label_set_markup (GTK_LABEL (self->notification_label), str);
 
-      // Remove old notifications
+      /* Remove old notifications */
       if (self->notification_timeout_id != 0)
         g_source_remove (self->notification_timeout_id);
 
       self->notification_timeout_id = g_timeout_add_seconds (5, hide_notification_scheduled, user_data);
 
-      // Disable the source, so it gets hidden
+      /* Disable the source, so it gets hidden */
       gcal_manager_disable_source (self->manager, self->removed_source);
 
       g_list_free (children);
@@ -1840,7 +1715,7 @@ gcal_source_dialog_constructed (GObject *object)
 
   g_object_set_data (G_OBJECT (self->remove_button), "response", GINT_TO_POINTER (GCAL_RESPONSE_REMOVE_SOURCE));
 
-  // Setup listbox header functions
+  /* Setup listbox header functions */
   gtk_list_box_set_header_func (GTK_LIST_BOX (self->calendars_listbox), display_header_func, NULL, NULL);
   gtk_list_box_set_sort_func (GTK_LIST_BOX (self->calendars_listbox), (GtkListBoxSortFunc) calendar_listbox_sort_func,
                               object, NULL);
@@ -1849,13 +1724,13 @@ gcal_source_dialog_constructed (GObject *object)
   gtk_list_box_set_sort_func (GTK_LIST_BOX (self->online_accounts_listbox), (GtkListBoxSortFunc) online_accounts_listbox_sort_func,
                               object, NULL);
 
-  // Action group
+  /* Action group */
   self->action_group = g_simple_action_group_new ();
   gtk_widget_insert_action_group (GTK_WIDGET (object), "source", G_ACTION_GROUP (self->action_group));
 
   g_action_map_add_action_entries (G_ACTION_MAP (self->action_group), actions, G_N_ELEMENTS (actions), object);
 
-  // Load the "Add" button menu
+  /* Load the "Add" button menu */
   builder = gtk_builder_new_from_resource ("/org/gnome/calendar/gtk/menus.ui");
 
   menu = G_MENU_MODEL (gtk_builder_get_object (builder, "add-source-menu"));
@@ -2186,11 +2061,11 @@ loading_changed_cb (GcalSourceDialog *dialog)
 
 /**
  * gcal_source_dialog_set_manager:
+ * @dialog: a #GcalSourceDialog
+ * @manager: a #GcalManager
  *
- * Setup the {@link GcalManager} singleton
+ * Setup the #GcalManager singleton
  * instance of the application.
- *
- * Returns:
  */
 void
 gcal_source_dialog_set_manager (GcalSourceDialog *dialog,
@@ -2221,13 +2096,12 @@ gcal_source_dialog_set_manager (GcalSourceDialog *dialog,
 
 /**
  * gcal_source_dialog_set_mode:
+ * @dialog: a #GcalSourceDialog
+ * @mode: a #GcalSourceDialogMode
  *
- * Set the source dialog mode. Creation
+ * Set the source dialog mode. Creation mode means that a new
- * mode means that a new calendar will
+ * calendar will be created, while edit mode means a calendar
- * be created, while edit mode means a
+ * will be edited.
- * calendar will be edited.
- *
- * Returns:
  */
 void
 gcal_source_dialog_set_mode (GcalSourceDialog    *dialog,
@@ -2237,7 +2111,7 @@ gcal_source_dialog_set_mode (GcalSourceDialog    *dialog,
 
   dialog->mode = mode;
 
-  // Cleanup old data
+  /* Cleanup old data */
   clear_pages (dialog);
 
   switch (mode)
@@ -2258,7 +2132,7 @@ gcal_source_dialog_set_mode (GcalSourceDialog    *dialog,
       break;
 
     case GCAL_SOURCE_DIALOG_MODE_EDIT:
-      // Bind title
+      /* Bind title */
       if (dialog->title_bind == NULL)
         {
           dialog->title_bind = g_object_bind_property (dialog->name_entry, "text", dialog->headerbar, "title",
@@ -2287,10 +2161,10 @@ gcal_source_dialog_set_mode (GcalSourceDialog    *dialog,
 
 /**
  * gcal_source_dialog_set_source:
+ * @dialog: a #GcalSourceDialog
+ * @source: an #ESource
  *
  * Sets the source to be edited by the user.
- *
- * Returns:
  */
 void
 gcal_source_dialog_set_source (GcalSourceDialog *dialog,

src/gcal-source-dialog.h

@@ -35,6 +35,15 @@ G_BEGIN_DECLS
 
 G_DECLARE_FINAL_TYPE (GcalSourceDialog, gcal_source_dialog, GCAL, SOURCE_DIALOG, GtkDialog)
 
+/**
+ * GcalSourceDialogMode:
+ * @GCAL_SOURCE_DIALOG_MODE_CREATE: creating a new calendar
+ * @GCAL_SOURCE_DIALOG_MODE_CREATE_WEB: creating a new web-based calendar
+ * @GCAL_SOURCE_DIALOG_MODE_EDIT: editing an existing calendar
+ * @GCAL_SOURCE_DIALOG_MODE_NORMAL: showing the list of calendars and online accounts
+ *
+ * The current action of the #GcalSourceDialog
+ */
 typedef enum
 {
   GCAL_SOURCE_DIALOG_MODE_CREATE,

src/gcal-utils.c

@@ -36,6 +36,12 @@
 #include <string.h>
 #include <math.h>
 
+/**
+ * SECTION:gcal-utils
+ * @short_description: Utility functions
+ * @title:Utility functions
+ */
+
 static const gint
 ab_day[7] =
 {
@@ -69,6 +75,16 @@ month_item[12] =
 
 G_DEFINE_BOXED_TYPE (icaltimetype, icaltime, gcal_dup_icaltime, g_free)
 
+/**
+ * datetime_compare_date:
+ * @dt1: (nullable): a #GDateTime
+ * @dt2: (nullable): a #GDateTime
+ *
+ * Compares the dates of @dt1 and @dt2. The times are
+ * ignored.
+ *
+ * Returns: negative, 0 or positive
+ */
 gint
 datetime_compare_date (GDateTime *dt1,
                        GDateTime *dt2)
@@ -92,6 +108,14 @@ datetime_compare_date (GDateTime *dt1,
   return 0;
 }
 
+/**
+ * datetime_to_icaltime:
+ * @dt: a #GDateTime
+ *
+ * Converts the #GDateTime's @dt to an #icaltimetype.
+ *
+ * Returns: (transfer full): a #icaltimetype.
+ */
 icaltimetype*
 datetime_to_icaltime (GDateTime *dt)
 {
@@ -115,6 +139,15 @@ datetime_to_icaltime (GDateTime *dt)
   return idt;
 }
 
+/**
+ * icaltime_to_datetime:
+ * @date: an #icaltimetype
+ *
+ * Converts the #icaltimetype's @date to a #GDateTime. The
+ * timezone is preserved.
+ *
+ * Returns: (transfer full): a #GDateTime.
+ */
 GDateTime*
 icaltime_to_datetime (const icaltimetype  *date)
 {
@@ -135,6 +168,17 @@ icaltime_to_datetime (const icaltimetype  *date)
   return dt;
 }
 
+/**
+ * datetime_is_date:
+ * @dt: a #GDateTime
+ *
+ * Checks if @dt represents a date. A pure date
+ * has the values of hour, minutes and seconds set
+ * to 0.
+ *
+ * Returns: %TRUE if @dt is a date, %FALSE if it's a
+ * timed datetime.
+ */
 gboolean
 datetime_is_date (GDateTime *dt)
 {
@@ -143,6 +187,14 @@ datetime_is_date (GDateTime *dt)
          g_date_time_get_seconds (dt) == 0;
 }
 
+/**
+ * gcal_dup_icaltime:
+ * @date: an #icaltimetype
+ *
+ * Creates an exact copy of @date.
+ *
+ * Returns: (transfer full): an #icaltimetype
+ */
 icaltimetype*
 gcal_dup_icaltime (const icaltimetype *date)
 {
@@ -166,12 +218,28 @@ gcal_dup_icaltime (const icaltimetype *date)
   return new_date;
 }
 
+/**
+ * gcal_get_weekday:
+ * @i: the weekday index
+ *
+ * Retrieves the weekday name.
+ *
+ * Returns: (transfer full): the weekday name
+ */
 gchar*
 gcal_get_weekday (gint i)
 {
   return nl_langinfo (ab_day[i]);
 }
 
+/**
+ * gcal_get_month_name:
+ * @i: the month index
+ *
+ * Retrieves the month name.
+ *
+ * Returns: (transfer full): the month name
+ */
 gchar*
 gcal_get_month_name (gint i)
 {
@@ -179,14 +247,15 @@ gcal_get_month_name (gint i)
 }
 
 /**
- * gcal_get_pixbuf_from_color:
+ * gcal_get_surface_from_color:
- * @color:
+ * @color: a #GdkRGBA
- * @size:
+ * @size: the size of the surface
  *
- * Create a pixbuf of a simple {@link GdkRGBA} color.
+ * Creates a squared surface filled with @color. The
+ * surface is always @size x @size.
  *
- * Returns: (Transfer full): An instance of {@link GdkPixbuf} to be freed with g_object_unref()
+ * Returns: (transfer full): a #cairo_surface_t
- **/
+ */
 cairo_surface_t*
 gcal_get_surface_from_color (GdkRGBA  *color,
                              gint      size)
@@ -210,6 +279,16 @@ gcal_get_surface_from_color (GdkRGBA  *color,
   return surface;
 }
 
+/**
+ * get_circle_surface_from_color:
+ * @color: a #GdkRGBA
+ * @size: the size of the surface
+ *
+ * Creates a circular surface filled with @color. The
+ * surface is always @size x @size.
+ *
+ * Returns: (transfer full): a #cairo_surface_t
+ */
 cairo_surface_t*
 get_circle_surface_from_color (GdkRGBA *color,
                                gint     size)
@@ -232,8 +311,16 @@ get_circle_surface_from_color (GdkRGBA *color,
   return surface;
 }
 
+/**
+ * get_color_name_from_source:
+ * @source: an #ESource
+ * @out_color: return value for the color
+ *
+ * Utility function to retrieve the color from @source.
+ */
 void
-get_color_name_from_source (ESource *source, GdkRGBA *out_color)
+get_color_name_from_source (ESource *source,
+                            GdkRGBA *out_color)
 {
   ESourceSelectable *extension = E_SOURCE_SELECTABLE (e_source_get_extension (source, E_SOURCE_EXTENSION_CALENDAR));
 
@@ -244,13 +331,15 @@ get_color_name_from_source (ESource *source, GdkRGBA *out_color)
 
 /**
  * get_desc_from_component:
- * @component:
+ * @component: an #ECalComponent
+ * @joint_char: the character to use when merging event comments
  *
  * Utility method to handle the extraction of the description from an
  * #ECalComponent. This cycle through the list of #ECalComponentText
  * and concatenate each string into one.
  *
- * Returns: (Transfer full) a new allocated string with the description
+ * Returns: (nullable)(transfer full) a new allocated string with the
+ * description
  **/
 gchar*
 get_desc_from_component (ECalComponent *component,
@@ -387,7 +476,7 @@ get_first_weekday (void)
  *
  * Create a component with the provided details
  *
- * Returns: (Transfer full): an {@link ECalComponent} object
+ * Returns: (transfer full): an {@link ECalComponent} object
  **/
 ECalComponent*
 build_component_from_details (const gchar *summary,
@@ -459,12 +548,15 @@ build_component_from_details (const gchar *summary,
 
 /**
  * icaltime_compare_date:
- * @date1:
+ * @date1: an #icaltimetype
- * @date2:
+ * @date2: an #icaltimetype
  *
- * Compare date parts of {@link icaltimetype} objects. Return negative value, 0 or positive value
+ * Compare date parts of #icaltimetype objects. Returns negative value,
- * accordingly if date1 is before, same day of after date2.
+ * 0 or positive value accordingly if @date1 is before, same day of
- * As a bonus it returns the amount of days passed between two days on the same year.
+ * after date2.
+ *
+ * As a bonus it returns the amount of days passed between two days on the
+ * same year.
  *
  * Returns: negative, 0 or positive
  **/
@@ -484,6 +576,18 @@ icaltime_compare_date (const icaltimetype *date1,
            time_day_of_year (date2->day, date2->month - 1, date2->year);
 }
 
+/**
+ * icaltime_compare_with_current:
+ * @date1: an #icaltimetype
+ * @date2: an #icaltimetype
+ * @current_time_t: the current time
+ *
+ * Compares @date1 and @date2 against the current time. Dates
+ * closer to the current date are sorted before.
+ *
+ * Returns: negative if @date1 comes after @date2, 0 if they're
+ * equal, positive otherwise
+ */
 gint
 icaltime_compare_with_current (const icaltimetype *date1,
                                const icaltimetype *date2,
@@ -517,6 +621,17 @@ icaltime_compare_with_current (const icaltimetype *date1,
   return result;
 }
 
+/**
+ * get_start_of_week:
+ * @date: an #icaltimetype
+ *
+ * Retrieves the start of the week that @date
+ * falls in. This function already takes the
+ * first weekday into account.
+ *
+ * Returns: (transfer full): a #GDateTime with
+ * the start of the week.
+ */
 GDateTime*
 get_start_of_week (icaltimetype *date)
 {
@@ -541,6 +656,17 @@ get_start_of_week (icaltimetype *date)
   return dt;
 }
 
+/**
+ * get_end_of_week:
+ * @date: an #icaltimetype
+ *
+ * Retrieves the end of the week that @date
+ * falls in. This function already takes the
+ * first weekday into account.
+ *
+ * Returns: (transfer full): a #GDateTime with
+ * the end of the week.
+ */
 GDateTime*
 get_end_of_week (icaltimetype *date)
 {
@@ -554,6 +680,15 @@ get_end_of_week (icaltimetype *date)
   return week_end;
 }
 
+/**
+ * is_clock_format_24h:
+ *
+ * Retrieves whether the current clock format is
+ * 12h or 24h based.
+ *
+ * Returns: %TRUE if the clock format is 24h, %FALSE
+ * otherwise.
+ */
 gboolean
 is_clock_format_24h (void)
 {
@@ -568,7 +703,10 @@ is_clock_format_24h (void)
   return g_strcmp0 (clock_format, "24h") == 0;
 }
 
-/* Function to do a last minute fixup of the AM/PM stuff if the locale
+/**
+ * e_strftime_fix_am_pm:
+ *
+ * Function to do a last minute fixup of the AM/PM stuff if the locale
  * and gettext haven't done it right. Most English speaking countries
  * except the USA use the 24 hour clock (UK, Australia etc). However
  * since they are English nobody bothers to write a language
@@ -584,7 +722,6 @@ is_clock_format_24h (void)
  * TODO: Actually remove the '%p' from the fixed up string so that
  * there isn't a stray space.
  */
-
 gsize
 e_strftime_fix_am_pm (gchar *str,
                       gsize max,
@@ -627,6 +764,14 @@ e_strftime_fix_am_pm (gchar *str,
   return (ret);
 }
 
+/**
+ * e_utf8_strftime_fix_am_pm:
+ *
+ * Stolen from Evolution codebase. Selects the
+ * correct time format.
+ *
+ * Returns: the size of the string
+ */
 gsize
 e_utf8_strftime_fix_am_pm (gchar *str,
                            gsize max,
@@ -748,9 +893,12 @@ fix_popover_menu_icons (GtkPopover *popover)
 
 /**
  * uri_get_fields:
+ * @uri: the URI
+ * @schema: (nullable): return location for the schema of the URI
+ * @host: (nullable): return location for the host of the URI
+ * @path: (nullable): return location for the resource path
  *
- * Split the given URI into the
+ * Split the given URI into the fields.
- * fields.
  *
  * Returns: #TRUE if @uri could be parsed, #FALSE otherwise
  */
@@ -809,6 +957,16 @@ uri_get_fields (const gchar  *uri,
   return valid;
 }
 
+/**
+ * get_source_parent_name_color:
+ * @manager: a #GcalManager
+ * @source: an #ESource
+ * @name: (nullable): return location for the name
+ * @color: (nullable): return location for the color
+ *
+ * Retrieves the name and the color of the #ESource that is
+ * parent of @source.
+ */
 void
 get_source_parent_name_color (GcalManager  *manager,
                               ESource      *source,
@@ -834,6 +992,16 @@ get_source_parent_name_color (GcalManager  *manager,
     }
 }
 
+/**
+ * format_utc_offset:
+ * @offset: an UTC offset
+ *
+ * Formats the UTC offset to a string that GTimeZone can
+ * parse. E.g. "-0300" or "+0530".
+ *
+ * Returns: (transfer full): a string representing the
+ * offset
+ */
 gchar*
 format_utc_offset (gint64 offset)
 {
@@ -859,6 +1027,17 @@ format_utc_offset (gint64 offset)
     return g_strdup_printf ("%s%02i%02i", sign, hours, minutes);
 }
 
+/**
+ * get_alarm_trigger_minutes:
+ * @event: a #GcalEvent
+ * @alarm: a #ECalComponentAlarm
+ *
+ * Calculates the number of minutes before @event's
+ * start time that the alarm should be triggered.
+ *
+ * Returns: the number of minutes before the event
+ * start that @alarm will be triggered.
+ */
 gint
 get_alarm_trigger_minutes (GcalEvent          *event,
                            ECalComponentAlarm *alarm)
@@ -891,6 +1070,18 @@ get_alarm_trigger_minutes (GcalEvent          *event,
   return diff;
 }
 
+/**
+ * should_change_date_for_scroll:
+ * @scroll_value: the current scroll value
+ * @scroll_event: the #GdkEventScroll that is being parsed
+ *
+ * Utility function to check if the date should change based
+ * on the scroll. The date is changed when the user scrolls
+ * too much on touchpad, or performs a rotation of the scroll
+ * button in a mouse.
+ *
+ * Returns: %TRUE if the date should change, %FALSE otherwise.
+ */
 gboolean
 should_change_date_for_scroll (gdouble        *scroll_value,
                                GdkEventScroll *scroll_event)
@@ -925,6 +1116,15 @@ should_change_date_for_scroll (gdouble        *scroll_value,
   return FALSE;
 }
 
+/**
+ * is_source_enabled:
+ * @source: an #ESource
+ *
+ * Retrieves whether the @source is enabled or not.
+ * Disabled sources don't show their events.
+ *
+ * Returns: %TRUE if @source is enabled, %FALSE otherwise.
+ */
 gboolean
 is_source_enabled (ESource *source)
 {

src/gcal-utils.h

@@ -33,6 +33,17 @@
 
 #define gcal_clear_datetime(dt) g_clear_pointer (dt, g_date_time_unref)
 
+/**
+ * GcalWindowViewType:
+ * @GCAL_WINDOW_VIEW_DAY: Day view (not implemented)
+ * @GCAL_WINDOW_VIEW_WEEK: Week view
+ * @GCAL_WINDOW_VIEW_MONTH: Month view
+ * @GCAL_WINDOW_VIEW_YEAR: Year view
+ * @GCAL_WINDOW_VIEW_LIST: List (not implemented)
+ * @GCAL_WINDOW_VIEW_SEARCH: Search view (partially implemented)
+ *
+ * Enum with the available views.
+ */
 typedef enum
 {
   GCAL_WINDOW_VIEW_DAY,
@@ -43,19 +54,6 @@ typedef enum
   GCAL_WINDOW_VIEW_SEARCH,
 } GcalWindowViewType;
 
-typedef enum
-{
-  EVENT_SUMMARY = 0,
-  EVENT_START_DATE,
-  EVENT_END_DATE,
-  EVENT_LOCATION,
-  EVENT_DESCRIPTION,
-  EVENT_SOURCE,
-} EventEditableProperty;
-
-typedef
-const gchar*  (*GcalTranslateFunc)                              (GtkWidget             *source_widget);
-
 GType           icaltime_get_type                               (void)            G_GNUC_CONST;
 
 gint            datetime_compare_date                           (GDateTime             *dt1,

src/gcal-window.c

@@ -39,6 +39,48 @@
 #include <libecal/libecal.h>
 #include <libical/icaltime.h>
 
+/**
+ * SECTION:gcal-window
+ * @short_description: Main window of GNOME Calendar
+ * @title:GcalWindow
+ * @stability:unstable
+ * @image:gcal-window.png
+ *
+ * #GcalWindow is the main window of GNOME Calendar, and contains
+ * the views, the source dialog, the edit dialog, and manages the
+ * calendar toggler popover menu.
+ *
+ * Besides that, #GcalWindow is also responsible for #GcalQuickAddPopover,
+ * and it responds to the #GcalView:create-event signal by positioning
+ * the quick add popover at the requested position.
+ *
+ * ## Calendar popover
+ *
+ * ![The popover](gcal-window_agendas.png)
+ *
+ * The calendar popover enables/disables the selected calendars.
+ * This is simply an UI for gcal_manager_enable_source() and
+ * gcal_manager_disable_source().
+ *
+ * The calendar popover also contains a button to open the source
+ * dialog.
+ *
+ * ## Edit dialog
+ *
+ * When an event is clicked, the views send the `event-activated`
+ * signal. #GcalWindow responds to this signal opening #GcalEditDialog
+ * with the clicked event.
+ *
+ * When #GcalEditDialog sends a response, #GcalWindow reacts by
+ * either propagating to gcal_manager_update_event(), or hiding
+ * the delete event widgets from the views.
+ *
+ * ## Source dialog
+ *
+ * The interaction with the source dialog is almost none. #GcalWindow
+ * just shows and hides it.
+ */
+
 typedef struct
 {
   gint               x;
@@ -1572,6 +1614,17 @@ gcal_window_init (GcalWindow *self)
 }
 
 /* Public API */
+/**
+ * gcal_window_new_with_view_and_date:
+ * @app: a #GcalApplication
+ * @view_type: a #GcalWindowViewType
+ * @date: the active date
+ *
+ * Creates a #GcalWindow, positions it at @date and shows
+ * @view_type view by default.
+ *
+ * Returns: (transfer full): a #GcalWindow
+ */
 GtkWidget*
 gcal_window_new_with_view_and_date (GcalApplication    *app,
                                     GcalWindowViewType  view_type,
@@ -1609,6 +1662,12 @@ gcal_window_new_with_view_and_date (GcalApplication    *app,
 }
 
 /* new-event interaction: first variant */
+/**
+ * gcal_window_new_event:
+ * @self: a #GcalWindow
+ *
+ * Makes #GcalWindow create a new event.
+ */
 void
 gcal_window_new_event (GcalWindow *self)
 {
@@ -1640,6 +1699,15 @@ gcal_window_new_event (GcalWindow *self)
   create_event_detailed_cb (NULL, start_date, end_date, self);
 }
 
+/**
+ * gcal_window_set_search_mode:
+ * @self: a #GcalWindow
+ * @enabled: whether the search mode is enabled or not
+ *
+ * Sets whether #GcalWindow is in search mode. This is used by
+ * #GcalShellSearchProvider to respond to the user clicking on
+ * GNOME Calendar icon at the search.
+ */
 void
 gcal_window_set_search_mode (GcalWindow *self,
                              gboolean    enabled)
@@ -1650,6 +1718,15 @@ gcal_window_set_search_mode (GcalWindow *self,
   gtk_search_bar_set_search_mode (GTK_SEARCH_BAR (self->search_bar), enabled);
 }
 
+/**
+ * gcal_window_set_search_query:
+ * @self: a #GcalWindow
+ * @query: sets the search query of @self
+ *
+ * Sets the search query of the search. #GcalWindow only
+ * propagates this to the search bar, which ends up
+ * triggering the search.
+ */
 void
 gcal_window_set_search_query (GcalWindow  *self,
                               const gchar *query)
@@ -1659,6 +1736,14 @@ gcal_window_set_search_query (GcalWindow  *self,
   gtk_entry_set_text (GTK_ENTRY (self->search_entry), query);
 }
 
+/**
+ * gcal_window_open_event_by_uuid:
+ * @self: a #GcalWindow
+ * @uuid: the unique identifier of the event to be opened
+ *
+ * Tells @self to open the event with @uuid. When it fails to
+ * open the event, it waits for 2 seconds before trying again.
+ */
 void
 gcal_window_open_event_by_uuid (GcalWindow  *self,
                                 const gchar *uuid)

src/views/gcal-range-tree.c

@@ -20,6 +20,28 @@
 
 #include "gcal-range-tree.h"
 
+/**
+ * SECTION:gcal-range-tree
+ * @short_description: Augmented AVL tree to handle ranges
+ * @title:GcalRangeTree
+ * @stability:stable
+ *
+ * #GcalRangeTree is an augmented AVL tree implemented to be
+ * able to handle ranges rather than point values. This tree
+ * is used by @GcalWeekGrid to store events according to their
+ * start and end minutes, and thus all the data structure was
+ * optimized to handle a limited subset of values.
+ *
+ * In the future, we may need to extend support for broader
+ * range values, and move away from guint16 in function params.
+ *
+ * # Ranges
+ *
+ * Conforming to the overall standard of iCal and Calendar,
+ * the start of a range is inclusive but the end of the range
+ * is always exclusive.
+ */
+
 typedef struct _Node
 {
   struct _Node       *left;
@@ -587,6 +609,17 @@ gcal_range_tree_get_data_at_range (GcalRangeTree *self,
   return data;
 }
 
+/**
+ * gcal_range_tree_count_entries_at_range:
+ * @self: a #GcalRangeTree
+ * @start: start of the range
+ * @end: end of the range
+ *
+ * Counts the number of entries available in the given
+ * range.
+ *
+ * Returns: the number of entries in the given range
+ */
 guint64
 gcal_range_tree_count_entries_at_range (GcalRangeTree *self,
                                         guint16        start,

src/views/gcal-range-tree.h

@@ -27,6 +27,17 @@ G_BEGIN_DECLS
 
 typedef struct _GcalRangeTree GcalRangeTree;
 
+/**
+ * GcalRangeTraverseFunc:
+ * @start: start of range of the entry
+ * @end: end of range of the entry
+ * @data: (nullable): the data of the entry
+ * @user_data: (closure): user data passed to the function
+ *
+ * Function type to be called when traversing a #GcalRangeTree.
+ *
+ * Returns: %TRUE to stop traversing, %FALSE to continue traversing
+ */
 typedef gboolean    (*GcalRangeTraverseFunc)                     (guint16             start,
                                                                   guint16             end,
                                                                   gpointer            data,