mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2025-01-12 10:25:33 +00:00
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>
This commit is contained in:
Mathieu Duponchelle
GStreamer Merge Bot
parent
f1f226f811
commit
d7e2861398
3 changed files with 20 additions and 42 deletions
|
|
@ -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.
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in a new issue