libical-glib: Correct annotations in the code comments

This fixes some of the annotations reported as incorrect with gobject-introspection
and gtk-doc warnings during the build with these enabled.

Closes libical#260

docs/reference/libical-glib/CMakeLists.txt

@@ -38,7 +38,7 @@ set(SOURCEDIRS ${PROJECT_BINARY_DIR}/src/libical-glib)
 
 set(DEPENDENCIES ical-glib)
 
-set(IGNORE_HEADERS libical-glib-private.h)
+set(IGNORE_HEADERS libical-glib-private.h i-cal-forward-declarations.h)
 
 set(extra_ldflags "")
 if(CMAKE_C_COMPILER_IS_GCC OR CMAKE_C_COMPILER_IS_CLANG)

src/libical-glib/api/i-cal-array.xml

@@ -51,7 +51,7 @@
     </method>
     <method name="i_cal_array_sort" corresponds="CUSTOM" annotation="skip" kind="others" since="1.0">
         <parameter type="ICalArray *" name="array" comment="The #ICalArray to be sorted"/>
-        <parameter type="gint (*compare)" name="(const void *, const void *)" annotation="scope call" comment="FULL: @compare: (scope call): The compare function"/>
+        <parameter type="gint (*compare)" name="(const void *, const void *)" comment="FULL:@compare: The compare function"/>
         <comment xml:space="preserve">Does not work right now. Sorts the @array using the sort function @compare.</comment>
         <custom>	g_return_if_fail (I_CAL_IS_ARRAY (array));
 	g_return_if_fail (array != NULL);

src/libical-glib/api/i-cal-attach.xml

@@ -32,7 +32,7 @@ static void unref_g_bytes(char *data, void *user_data)
     g_bytes_unref(bytes);
 }</declaration>
     <method name="i_cal_attach_new_from_bytes" corresponds="CUSTOM" kind="constructor" since="1.0">
-        <parameter type="GBytes *" annotation="transfer full" name="bytes" comment="The #GBytes holding the data used to create the #ICalAttach"/>
+        <parameter type="GBytes *" annotation="transfer full" name="bytes" comment="The GBytes holding the data used to create the #ICalAttach"/>
         <returns type="ICalAttach *" annotation="transfer full" comment="The newly created #ICalAttach" />
         <comment xml:space="preserve">Creates a new #ICalAttach from the data in bytes. Takes a reference of @bytes, increase the reference before calling this function if you with to use it afterward. The stored bytes should be already encoded with used encoding (like base64).</comment>
         <custom>    g_return_val_if_fail (bytes != NULL, NULL);
@@ -54,12 +54,12 @@ static void unref_g_bytes(char *data, void *user_data)
     </method>
     <method name="i_cal_attach_get_url" corresponds="icalattach_get_url" kind="others" since="1.0">
         <parameter type="ICalAttach *" name="attach" comment="The #ICalAttach to be queried"/>
-        <returns type="const gchar *" annotation="nullable, transfer none" comment="The url component of the @attach. %NULL if it is built from data or there is an error." />
+        <returns type="const gchar *" annotation="nullable, transfer none" comment="The url component of the @attach. NULL if it is built from data or there is an error." />
         <comment xml:space="preserve">Gets the url, if the #ICalAttach is built from the url.</comment>
     </method>
     <method name="i_cal_attach_get_data" corresponds="CUSTOM" kind="others" since="1.0">
         <parameter type="ICalAttach *" name="attach" comment="The #ICalAttach to be queried"/>
-        <returns type="const gchar *" annotation="nullable, transfer none" comment="The data component of the @attach. %NULL if it is built from url or there is an error." />
+        <returns type="const gchar *" annotation="nullable, transfer none" comment="The data component of the @attach. NULL if it is built from url or there is an error." />
         <comment xml:space="preserve">Gets the data, if the #ICalAttach is built from the data.</comment>
         <custom>    g_return_val_if_fail (I_CAL_IS_ATTACH (attach), NULL);
 

src/libical-glib/api/i-cal-component.xml

@@ -472,8 +472,8 @@ static void foreach_tzid_cb(icalparameter *in_param, void *user_data)
 }</declaration>
     <method name="i_cal_component_foreach_tzid" corresponds="CUSTOM" kind="other" since="3.0.5">
         <parameter type="ICalComponent *" name="comp" comment="The #ICalComponent to be queried"/>
-        <parameter type="ICalComponentForeachTZIDFunc" name="callback" annotation="scope call" comment="The callback function"/>
-        <parameter type="gpointer" name="user_data" annotation="nullable, closure callback" comment="The data for callback function"/>
+        <parameter type="ICalComponentForeachTZIDFunc" name="callback" annotation="scope call, closure user_data" comment="The callback function"/>
+        <parameter type="gpointer" name="user_data" annotation="nullable" comment="The data for callback function"/>
         <comment>Applies the same manipulation on every tzid in #ICalComponent.</comment>
         <custom>    struct ForeachTZIDData data;
     icalcomponent *native_comp;
@@ -514,8 +514,8 @@ static void foreach_recurrence_cb(icalcomponent *in_comp, struct icaltime_span *
         <parameter type="ICalComponent *" name="comp" comment="The #ICalComponent to be queried"/>
         <parameter type="ICalTime *" name="start" comment="Ignore timespans before this"/>
         <parameter type="ICalTime *" name="end" comment="Ignore timespans after this"/>
-        <parameter type="ICalComponentForeachRecurrenceFunc" name="callback" annotation="scope call" comment="Function called for each timespan within the range"/>
-        <parameter type="gpointer" name="user_data" annotation="nullable, closure callback" comment="The user data for callback function"/>
+        <parameter type="ICalComponentForeachRecurrenceFunc" name="callback" annotation="scope call, closure user_data" comment="Function called for each timespan within the range"/>
+        <parameter type="gpointer" name="user_data" annotation="nullable" comment="The user data for callback function"/>
         <comment>Cycles through all recurrences of an event. This function will call the specified callback function for once for the base value of DTSTART, and foreach recurring date/time value. It will filter out events that are specified as an EXDATE or an EXRULE.</comment>
         <custom>    struct ForeachRecurrenceData data;
     icalcomponent *native_comp;

src/libical-glib/api/i-cal-mime.xml

@@ -16,12 +16,11 @@
  */
 typedef gchar *(*ICalMimeParseFunc)(gchar *bytes, size_t size, gpointer user_data);</declaration>
     <method name="i_cal_mime_parse" corresponds="CUSTOM" since="1.0">
-        <parameter type="ICalMimeParseFunc" name="func" annotation="scope call" comment="The parsing function"/>
-        <parameter type="gpointer" name="user_data" annotation="closure" comment="The date given to @func"/>
+        <parameter type="ICalMimeParseFunc" name="func" annotation="scope call, closure user_data" comment="The parsing function"/>
+        <parameter type="gpointer" name="user_data" annotation="nullable" comment="The user data given to the @func"/>
         <returns type="ICalComponent *" annotation="transfer full" comment="The parsed #ICalComponent"/>
         <comment xml:space="preserve">Parses data to #ICalComponent using the given function.</comment>
         <custom>	g_return_val_if_fail (func != NULL, NULL);
-	g_return_val_if_fail (user_data != NULL, NULL);
 
 	return i_cal_component_new_full (icalmime_parse(func, user_data), NULL);</custom>
     </method>

src/libical-glib/api/i-cal-parser.xml

@@ -48,8 +48,8 @@ typedef gchar *(*ICalParserLineGenFunc)(gchar *bytes, size_t size, gpointer user
     </method>
     <method name="i_cal_parser_parse" corresponds="CUSTOM" since="1.0">
         <parameter type="ICalParser *" name="parser" comment="The parser used to parse the string and output the #ICalComponent"/>
-        <parameter type="ICalParserLineGenFunc" name="func" annotation="scope call" comment="The function used to parse"/>
-        <parameter type="gpointer" name="user_data" annotation="closure" comment="The data given to @func"/>
+        <parameter type="ICalParserLineGenFunc" name="func" annotation="scope call, closure user_data" comment="The function used to parse"/>
+        <parameter type="gpointer" name="user_data" annotation="nullable" comment="The data given to @func"/>
         <returns type="ICalComponent *" annotation="transfer full" comment="The component output by the parser."/>
         <comment xml:space="preserve">icalparser_parse takes a string that holds the text ( in RFC 2445 format ) and returns a pointer to an #ICalComponent. The caller owns the memory. @func is a pointer to a function that returns one content line per invocation.</comment>
         <custom>	g_return_val_if_fail (parser != NULL &amp;&amp; func != NULL, NULL);
@@ -64,8 +64,8 @@ typedef gchar *(*ICalParserLineGenFunc)(gchar *bytes, size_t size, gpointer user
     </method>
     <method name="i_cal_parser_get_line" corresponds="CUSTOM" since="1.0">
         <parameter type="ICalParser *" name="parser" comment="The parser to be queried"/>
-        <parameter type="ICalParserLineGenFunc" name="func" annotation="scope call" comment="A line generator function"/>
-        <parameter type="gpointer" name="user_data" annotation="closure" comment="The data given to @func"/>
+        <parameter type="ICalParserLineGenFunc" name="func" annotation="scope call, closure user_data" comment="A line generator function"/>
+        <parameter type="gpointer" name="user_data" annotation="nullable" comment="The data given to @func"/>
         <returns type="gchar *" annotation="transfer full" comment="A single iCal content line."/>
         <comment xml:space="preserve">Given a line generator function, returns a single iCal content line.</comment>
         <custom>gchar *line, *linecopy;

src/libical-glib/api/i-cal-recurrence.xml

@@ -115,7 +115,7 @@
     </method>
     <method name="i_cal_recurrence_encode_month" corresponds="icalrecurrencetype_encode_month" since="3.0.5">
         <parameter type="gint" name="month" comment="The month to be encoded"/>
-        <parameter type="gboolean" name="is_leap" comment="%TRUE, when the month is leap, %FALSE otherwise"/>
+        <parameter type="gboolean" name="is_leap" comment="TRUE, when the month is leap, FALSE otherwise"/>
         <returns type="gshort" comment="Encoded @month and @is_leap"/>
         <comment xml:space="preserve">Encodes the @month and the @is_leap flag into a single value, which can be split by i_cal_recurrence_month_is_leap() and i_cal_recurrence_month_month().</comment>
     </method>

src/libical-glib/api/i-cal-time-span.xml

@@ -11,7 +11,7 @@
         <parameter type="time_t" name="end" comment="End of the time span"/>
         <parameter type="gboolean" name="is_busy" comment="Whether the time span is busy"/>
         <returns type="ICalTimeSpan *" annotation="transfer full" comment="The newly created #ICalTimeSpan." />
-        <comment xml:space="preserve">Creates a new #ICalTimeSpan. Free it with g_object_unref(), when no longer needed.</comment>
+        <comment xml:space="preserve">Creates a new #ICalTimeSpan. Free it with g_object_unref, when no longer needed.</comment>
         <custom>    struct icaltime_span span;
     span.start = start;
     span.end = end;
@@ -21,7 +21,7 @@
     <method name="i_cal_time_span_clone" corresponds="CUSTOM" kind="constructor" since="3.0.5">
         <parameter type="const ICalTimeSpan *" name="src" comment="A time span to clone"/>
         <returns type="ICalTimeSpan *" annotation="transfer full" comment="The newly created #ICalTimeSpan, clone of @src." />
-        <comment xml:space="preserve">Creates a new #ICalTimeSpan, clone of @src. Free it with g_object_unref(), when no longer needed.</comment>
+        <comment xml:space="preserve">Creates a new #ICalTimeSpan, clone of @src. Free it with g_object_unref, when no longer needed.</comment>
         <custom>    struct icaltime_span *span;
     g_return_val_if_fail(I_CAL_IS_TIME_SPAN((ICalTimeSpan *)src), NULL);
     span = ((struct icaltime_span *)i_cal_object_get_native ((ICalObject *)src));

src/libical-glib/api/i-cal-time.xml

@@ -44,7 +44,7 @@
     <method name="i_cal_time_new_from_timet_with_zone" corresponds="icaltime_from_timet_with_zone" kind="others" since="1.0">
         <parameter type="const time_t" name="v" comment="The seconds past since epoch time"/>
         <parameter type="gint" name="is_date" comment="Whether it is a date type, 1 if yes, 0 if not"/>
-        <parameter type="ICalTimezone *" name="zone" annotation="nullable" comment="The timezone, or %NULL"/>
+        <parameter type="ICalTimezone *" name="zone" annotation="nullable" comment="The timezone, or NULL"/>
         <returns type="ICalTime *" annotation="transfer full" comment="The newly created #ICalTime" />
         <comment xml:space="preserve">Converts seconds past UNIX epoch to a timetype, using timezones.</comment>
     </method>
@@ -148,7 +148,7 @@
         <parameter type="const ICalTime *" name="b" annotation="in, transfer none" comment="The #ICalTime to be compared"/>
 	<parameter type="ICalTimezone *" name="zone" annotation="nullable" comment="The target timezone"/>
         <returns type="gint" comment="-1, 0, or 1 to indicate that a less than b, a==b or a larger than b." />
-        <comment xml:space="preserve">Like i_cal_time_compare_tz(), but only use the date parts; accepts timezone.</comment>
+        <comment xml:space="preserve">This converts both times to the given @zone and compares their date components.</comment>
     </method>
     <method name="i_cal_time_adjust" corresponds="icaltime_adjust" since="1.0">
         <parameter type="ICalTime *" name="tt" native_op="POINTER" comment="The #ICalTime to be set"/>

src/libical-glib/api/i-cal-timezone.xml

@@ -58,13 +58,13 @@
     </method>
     <method name="i_cal_timezone_get_tzid" corresponds="icaltimezone_get_tzid" kind="get" since="1.0">
         <parameter type="const ICalTimezone *" name="zone" annotation="nullable" comment="The #ICalTimezone to be queried"/>
-        <returns type="const gchar *" annotation="nullable" comment="The timezone id, or %NULL"/>
-        <comment xml:space="preserve">Returns the TZID of a timezone, or %NULL, when none is set or when @zone is also %NULL.</comment>
+        <returns type="const gchar *" annotation="nullable" comment="The timezone id, or NULL"/>
+        <comment xml:space="preserve">Returns the TZID of a timezone, or NULL, when none is set or when @zone is also NULL.</comment>
     </method>
     <method name="i_cal_timezone_get_location" corresponds="icaltimezone_get_location" kind="get" since="1.0">
         <parameter type="const ICalTimezone *" name="zone" annotation="nullable" comment="The #ICalTimezone to be queried"/>
-        <returns type="const gchar *" annotation="nullable" comment="The location of the #ICalTimezone, or %NULL"/>
-        <comment xml:space="preserve">Returns the city name of a timezone, or %NULL, when none is set or when @zone is also %NULL.</comment>
+        <returns type="const gchar *" annotation="nullable" comment="The location of the #ICalTimezone, or NULL"/>
+        <comment xml:space="preserve">Returns the city name of a timezone, or NULL, when none is set or when @zone is also NULL.</comment>
     </method>
     <method name="i_cal_timezone_get_tznames" corresponds="icaltimezone_get_tznames" kind="get" since="1.0">
         <parameter type="const ICalTimezone *" name="zone" annotation="nullable" comment="The #ICalTimezone to be queried"/>
@@ -121,7 +121,7 @@
     <method name="i_cal_timezone_get_utc_offset_of_utc_time" corresponds="icaltimezone_get_utc_offset_of_utc_time" kind="get" since="1.0">
         <parameter type="ICalTimezone *" name="zone" annotation="nullable" comment="The given #ICalTimezone"/>
         <parameter type="ICalTime *" name="tt" native_op="POINTER" comment="The local time"/>
-        <parameter type="gint *" name="is_daylight" annotation="out, optional" comment="Whether it is day light, can be %NULL"/>
+        <parameter type="gint *" name="is_daylight" annotation="out, optional" comment="Whether it is day light, can be NULL"/>
         <returns type="gint" comment="UTC offset of the @zone"/>
         <comment>Calculates the UTC offset of a given UTC time in the given timezone.  It is the number of seconds to add to UTC to get local time.  The is_daylight flag is set to 1 if the time is in daylight-savings time.</comment>
     </method>