From 96936912f3edb2ec2c01b3e91f8a23340ccc4d5d Mon Sep 17 00:00:00 2001 From: Michael Smith Date: Thu, 10 Nov 2005 10:17:01 +0000 Subject: [PATCH] Further improve query docs. Still not happy with this. Original commit message from CVS: Further improve query docs. Still not happy with this. --- gst/gstquery.c | 23 +++++++++++++++-------- gst/gstquery.h | 2 +- 2 files changed, 16 insertions(+), 9 deletions(-) diff --git a/gst/gstquery.c b/gst/gstquery.c index e384896..6ccdfa5 100644 --- a/gst/gstquery.c +++ b/gst/gstquery.c @@ -3,7 +3,7 @@ * 2000 Wim Taymans * 2005 Wim Taymans * - * gstquery.c: GstQueryType registration + * gstquery.c: GstQueryType registration and Query parsing/creation * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public @@ -23,14 +23,17 @@ /** * SECTION:gstquery - * @short_description: Dynamically register new query types and parse results + * @short_description: Dynamically register new query types. Provide functions + * to create queries, and to set and parse values in them. * @see_also: #GstPad, #GstElement * * GstQuery functions are used to register a new query types to the gstreamer * core. * Query types can be used to perform queries on pads and elements. * - * Query answer can be parsed using gst_query_parse_xxx() helpers. + * Queries can be created using the gst_query_new_xxx() functions. + * Query values can be set using gst_query_set_xxx(), and parsed using + * gst_query_parse_xxx() helpers. */ #include @@ -214,7 +217,7 @@ gst_query_type_register (const gchar * nick, const gchar * description) * gst_query_type_get_by_nick: * @nick: The nick of the query * - * Returns: The query registered with @nick or GST_QUERY_NONE + * Returns: The query registered with @nick or #GST_QUERY_NONE * if the query was not registered. */ GstQueryType @@ -329,7 +332,8 @@ gst_query_new (GstQueryType type, GstStructure * structure) * @format: the default #GstFormat for the new query * * Constructs a new query stream position query object. Use gst_query_unref() - * when done with it. + * when done with it. A position query is used to query the current position + * of playback in the streams, in some format. * * Returns: A #GstQuery */ @@ -396,7 +400,8 @@ gst_query_parse_position (GstQuery * query, GstFormat * format, gint64 * cur) * @format: the #GstFormat for this duration query * * Constructs a new stream duration query object to query in the given format. - * Use gst_query_unref() when done with it. + * Use gst_query_unref() when done with it. A duration query will give the + * total length of the stream. * * Returns: A #GstQuery */ @@ -467,7 +472,8 @@ gst_query_parse_duration (GstQuery * query, GstFormat * format, * @dest_format: the target #GstFormat * * Constructs a new convert query object. Use gst_query_unref() - * when done with it. + * when done with it. A convert query is used to ask for a conversion between + * one format and another. * * Returns: A #GstQuery */ @@ -555,7 +561,8 @@ gst_query_parse_convert (GstQuery * query, GstFormat * src_format, * @format: the #GstFormat for the new query * * Constructs a new segment query object. Use gst_query_unref() - * when done with it. + * when done with it. A segment query is used to discover information about the + * currently configured segment for playback. * * Returns: a #GstQuery */ diff --git a/gst/gstquery.h b/gst/gstquery.h index 8a7ba50..25b693b 100644 --- a/gst/gstquery.h +++ b/gst/gstquery.h @@ -44,7 +44,7 @@ G_BEGIN_DECLS * @GST_QUERY_RATE: current rate of the stream * @GST_QUERY_SEEKING: seeking capabilities * @GST_QUERY_SEGMENT: segment start/stop positions - * @GST_QUERY_CONVERT: convert values + * @GST_QUERY_CONVERT: convert values between formats * @GST_QUERY_FORMATS: query supported formats for convert * * Standard predefined Query types -- 2.7.4