Commit d7e28613 authored by Mathieu Duponchelle's avatar Mathieu Duponchelle 🐸 Committed by GStreamer Marge Bot
Browse files

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: <!759>
parent f1f226f8
Pipeline #271782 waiting for manual action with stages
in 43 seconds
......@@ -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
*
......
......@@ -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
*/
......
......@@ -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.
*/
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment