docs: standardize GstControlSource, GstDateTime documentation

* Don't repeat what annotations are stating with respect to ownership
  transfer, nullability

* Misc cleanup / typo fixes / addition of links

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/759>

3 files changed, 20 insertions, 42 deletions

diff --git a/gst/gstcontrolsource.h b/gst/gstcontrolsource.h
index 2c0f351e6a..cd2dfafe13 100644
--- a/gst/gstcontrolsource.h
+++ b/gst/gstcontrolsource.h
@@ -54,7 +54,7 @@ typedef struct _GstValueArray GstValueArray;
  * @timestamp: timestamp of the value change
  * @value: the corresponding value
  *
- * Structure for saving a timestamp and a value.
+ * Structure for storing a timestamp and a value.
  */
 struct _GstTimedValue
 {
@@ -84,7 +84,7 @@ typedef gboolean (* GstControlSourceGetValue) (GstControlSource *self,
  * @n_values: the number of values
  * @values: array to put control-values in
  *
- * Function for returning an array of values for starting at a given timestamp.
+ * Function for returning an array of values starting at a given timestamp.
  *
  * Returns: %TRUE if the values were successfully calculated.
  *
@@ -94,6 +94,7 @@ typedef gboolean (* GstControlSourceGetValueArray) (GstControlSource *self,
 
 /**
  * GstControlSource:
+ * @parent: the parent structure
  * @get_value: Function for returning a value for a given timestamp
  * @get_value_array: Function for returning a values array for a given timestamp
  *
diff --git a/gst/gstdatetime.c b/gst/gstdatetime.c
index 2b8c20ea6a..10e73e23e4 100644
--- a/gst/gstdatetime.c
+++ b/gst/gstdatetime.c
@@ -37,9 +37,11 @@
  * Struct to store date, time and timezone information altogether.
  * #GstDateTime is refcounted and immutable.
  *
- * Date information is handled using the proleptic Gregorian calendar.
+ * Date information is handled using the [proleptic Gregorian calendar].
  *
  * Provides basic creation functions and accessor functions to its fields.
+ *
+ * [proleptic Gregorian calendar]: https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar
  */
 
 typedef enum
@@ -70,12 +72,10 @@ static void gst_date_time_free (GstDateTime * datetime);
 
 /**
  * gst_date_time_new_from_g_date_time:
- * @dt: (transfer full) (nullable): the #GDateTime. The new #GstDateTime takes ownership.
+ * @dt: (transfer full) (nullable): the #GDateTime.
  *
  * Creates a new #GstDateTime from a #GDateTime object.
  *
- * Free-function: gst_date_time_unref
- *
  * Returns: (transfer full) (nullable): a newly created #GstDateTime,
  * or %NULL if @dt is %NULL.
  */
@@ -103,8 +103,6 @@ gst_date_time_new_from_g_date_time (GDateTime * dt)
  *
  * Creates a new #GDateTime from a fully defined #GstDateTime object.
  *
- * Free-function: g_date_time_unref
- *
  * Returns: (transfer full) (nullable): a newly created #GDateTime, or
  * %NULL on error or if @datetime does not have a year, month, day, hour,
  * minute and second.
@@ -196,7 +194,7 @@ gst_date_time_has_second (const GstDateTime * datetime)
  * gst_date_time_get_year:
  * @datetime: a #GstDateTime
  *
- * Returns the year of this #GstDateTime
+ * Returns the year of this #GstDateTime.
  * Call gst_date_time_has_year() before, to avoid warnings.
  *
  * Return value: The year of this #GstDateTime
@@ -359,8 +357,6 @@ gst_date_time_get_time_zone_offset (const GstDateTime * datetime)
  *
  * @year should be from 1 to 9999.
  *
- * Free-function: gst_date_time_unref
- *
  * Return value: (transfer full) (nullable): the newly created #GstDateTime,
  * or %NULL on error.
  */
@@ -383,8 +379,6 @@ gst_date_time_new_y (gint year)
  * If value is -1 then all over value will be ignored. For example
  * if @month == -1, then #GstDateTime will created only for @year.
  *
- * Free-function: gst_date_time_unref
- *
  * Return value: (transfer full) (nullable): the newly created #GstDateTime,
  * or %NULL on error.
  */
@@ -411,8 +405,6 @@ gst_date_time_new_ym (gint year, gint month)
  * @day == -1, then #GstDateTime will created for @year and @month and
  * so on.
  *
- * Free-function: gst_date_time_unref
- *
  * Return value: (transfer full) (nullable): the newly created #GstDateTime,
  * or %NULL on error.
  */
@@ -429,8 +421,6 @@ gst_date_time_new_ymd (gint year, gint month, gint day)
  * Creates a new #GstDateTime using the time since Jan 1, 1970 specified by
  * @secs. The #GstDateTime is in the local timezone.
  *
- * Free-function: gst_date_time_unref
- *
  * Return value: (transfer full) (nullable): the newly created #GstDateTime,
  * or %NULL on error.
  */
@@ -453,8 +443,6 @@ gst_date_time_new_from_unix_epoch_local_time (gint64 secs)
  * Creates a new #GstDateTime using the time since Jan 1, 1970 specified by
  * @secs. The #GstDateTime is in the UTC timezone.
  *
- * Free-function: gst_date_time_unref
- *
  * Return value: (transfer full) (nullable): the newly created #GstDateTime,
  * or %NULL on error.
  */
@@ -577,8 +565,6 @@ gst_date_time_check_fields (gint * year, gint * month, gint * day,
  * @month and @day, and the time fields will be considered not set. In this
  * case @minute and @seconds should also be -1.
  *
- * Free-function: gst_date_time_unref
- *
  * Return value: (transfer full) (nullable): the newly created #GstDateTime,
  * or %NULL on error.
  */
@@ -628,8 +614,6 @@ gst_date_time_new_local_time (gint year, gint month, gint day, gint hour,
  *
  * Creates a new #GstDateTime representing the current date and time.
  *
- * Free-function: gst_date_time_unref
- *
  * Return value: (transfer full) (nullable): the newly created #GstDateTime which should
  *     be freed with gst_date_time_unref(), or %NULL on error.
  */
@@ -651,8 +635,6 @@ gst_date_time_new_now_local_time (void)
  * Creates a new #GstDateTime that represents the current instant at Universal
  * coordinated time.
  *
- * Free-function: gst_date_time_unref
- *
  * Return value: (transfer full) (nullable): the newly created #GstDateTime which should
  *   be freed with gst_date_time_unref(), or %NULL on error.
  */
@@ -712,12 +694,10 @@ __gst_date_time_compare (const GstDateTime * dt1, const GstDateTime * dt2)
  * representing it in hours for most timezones.
  *
  * If value is -1 then all over value will be ignored. For example
- * if @month == -1, then #GstDateTime will created only for @year. If
- * @day == -1, then #GstDateTime will created for @year and @month and
+ * if @month == -1, then #GstDateTime will be created only for @year. If
+ * @day == -1, then #GstDateTime will be created for @year and @month and
  * so on.
  *
- * Free-function: gst_date_time_unref
- *
  * Return value: (transfer full) (nullable): the newly created #GstDateTime,
  * or %NULL on error.
  */
@@ -859,16 +839,15 @@ done:
 
 /**
  * gst_date_time_to_iso8601_string:
- * @datetime: GstDateTime.
+ * @datetime: a #GstDateTime.
  *
  * Create a minimal string compatible with ISO-8601. Possible output formats
- * are (for example): 2012, 2012-06, 2012-06-23, 2012-06-23T23:30Z,
- * 2012-06-23T23:30+0100, 2012-06-23T23:30:59Z, 2012-06-23T23:30:59+0100
+ * are (for example): `2012`, `2012-06`, `2012-06-23`, `2012-06-23T23:30Z`,
+ * `2012-06-23T23:30+0100`, `2012-06-23T23:30:59Z`, `2012-06-23T23:30:59+0100`
  *
  * Returns: (nullable): a newly allocated string formatted according
  *     to ISO 8601 and only including the datetime fields that are
- *     valid, or %NULL in case there was an error. The string should
- *     be freed with g_free().
+ *     valid, or %NULL in case there was an error.
  */
 gchar *
 gst_date_time_to_iso8601_string (GstDateTime * datetime)
@@ -887,15 +866,13 @@ gst_date_time_to_iso8601_string (GstDateTime * datetime)
  *
  * Tries to parse common variants of ISO-8601 datetime strings into a
  * #GstDateTime. Possible input formats are (for example):
- * 2012-06-30T22:46:43Z, 2012, 2012-06, 2012-06-30, 2012-06-30T22:46:43-0430,
- * 2012-06-30T22:46Z, 2012-06-30T22:46-0430, 2012-06-30 22:46,
- * 2012-06-30 22:46:43, 2012-06-00, 2012-00-00, 2012-00-30, 22:46:43Z, 22:46Z,
- * 22:46:43-0430, 22:46-0430, 22:46:30, 22:46
+ * `2012-06-30T22:46:43Z`, `2012`, `2012-06`, `2012-06-30`, `2012-06-30T22:46:43-0430`,
+ * `2012-06-30T22:46Z`, `2012-06-30T22:46-0430`, `2012-06-30 22:46`,
+ * `2012-06-30 22:46:43`, `2012-06-00`, `2012-00-00`, `2012-00-30`, `22:46:43Z`, `22:46Z`,
+ * `22:46:43-0430`, `22:46-0430`, `22:46:30`, `22:46`
  * If no date is provided, it is assumed to be "today" in the timezone
  * provided (if any), otherwise UTC.
  *
- * Free-function: gst_date_time_unref
- *
  * Returns: (transfer full) (nullable): a newly created #GstDateTime,
  * or %NULL on error
  */
diff --git a/gst/gstdatetime.h b/gst/gstdatetime.h
index ede2b44541..8d2b74770d 100644
--- a/gst/gstdatetime.h
+++ b/gst/gstdatetime.h
@@ -32,8 +32,8 @@ G_BEGIN_DECLS
  * GstDateTime:
  *
  * Opaque, immutable, refcounted struct that stores date, time and timezone
- * information. It currently supports ranges from 0001-01-01 to
- * 9999-12-31 in the Gregorian proleptic calendar.
+ * information. It currently supports ranges from `0001-01-01` to
+ * `9999-12-31` in the Gregorian proleptic calendar.
  *
  * Use the accessor functions to get the stored values.
  */